Thiết lập nhà cung cấp AI và mẫu tài liệu giao nhận¶
Thông tin hướng dẫn
Điều kiện cần có
Hướng dẫn này yêu cầu cài các ứng dụng/mô-đun sau:
Document Parsing - tiện ích trả phí cần cài riêng (khi Freight Forwarder Management đã hoạt động, việc cài tiện ích này sẽ tự động kích hoạt Freight Document Parsing, qua đó tải năm mẫu tài liệu giao nhận được kiểm tra trong hướng dẫn này)
Mỗi lần trích xuất bằng AI trong Điền booking hoặc lô hàng từ tài liệu bằng AI đều cần ít nhất một nhà cung cấp thực sự phản hồi. Nếu bỏ qua bước thiết lập này, người đầu tiên bấm Import from Document (Nhập từ tài liệu) sẽ gặp lỗi kết nối hoặc API key thay vì nhận được lô hàng đã điền thông tin, và có thể nhầm lỗi cấu hình với tính năng bị hỏng. Đây là bước thiết lập một lần cho mỗi công ty, không phải bước làm cho từng lô hàng.
Tình huống xuyên suốt: Hai Long Logistics bắt đầu với sáu nhà cung cấp được kèm theo mô-đun. Google Gemini được đặt làm mặc định sau khi cài. Trong hướng dẫn này, quản trị viên đặt nhà cung cấp OpenAI đã được phê duyệt làm mặc định và kiểm tra kết nối trước khi nhóm Chứng từ sử dụng.
Mở màn hình Nhà cung cấp AI¶
Vào .
Ghi chú
Màn hình này nằm ngay trong ứng dụng Settings (Thiết lập), không cần bật Chế độ nhà phát triển và không nằm dưới Technical (Kỹ thuật). Chỉ người dùng có mức truy cập Settings (Thiết lập) (base.group_system) tại , tab Access Rights (Quyền truy cập), mục Administration (Quản trị), mới có thể tạo hoặc sửa nhà cung cấp tại đây. Đây là mức quyền kỹ thuật cao hơn mức Administrator (Quản trị viên) của Freight mô tả trong quyền Giao nhận của người dùng tại Thiết lập > Người dùng & Công ty > Người dùng; ở một nhóm nhỏ như Hai Long Logistics, cùng một người (Duc) thường có cả hai quyền.
Danh sách có sáu nhà cung cấp được tạo sẵn với tên và mô hình mặc định nhưng chưa có API key: Google Gemini, Groq, OpenRouter, OpenAI, Anthropic Claude và Ollama (Local). Dòng Google Gemini đã được đánh dấu Default (Mặc định); đây là nhà cung cấp mà trình hướng dẫn Import from Document (Nhập từ tài liệu) chọn sẵn cho đến khi bạn đổi.
Mẹo
Thiết lập đúng khi: danh sách có đủ sáu nhà cung cấp tạo sẵn và dòng Google Gemini được đánh dấu Default (Mặc định).
Chọn nhà cung cấp AI cần thiết lập¶
Lựa chọn |
Sử dụng khi |
Điều gì thay đổi |
|---|---|---|
Dùng nhà cung cấp tạo sẵn (OpenAI trong hướng dẫn này) |
Công ty đã phê duyệt nhà cung cấp và mô hình để xử lý các tài liệu này |
Không cần tạo bản ghi mới; thêm API key của nhà cung cấp và chỉ đặt làm mặc định nếu nhóm muốn chọn sẵn nhà cung cấp đó |
Tạo nhà cung cấp Custom (OpenAI-compatible) |
Công ty vận hành điểm truy cập LLM riêng hoặc dùng nhà cung cấp chưa có trong danh sách tạo sẵn |
Bạn phải tự tạo bản ghi và điền API Base URL (URL gốc của API); Custom không có dữ liệu mẫu để bắt đầu |
Đổi mô hình của nhà cung cấp Ollama sang |
Bạn chạy AI cục bộ bằng Ollama và cần đọc ảnh quét hoặc PDF |
Mô hình mặc định tạo sẵn của Ollama ( |
Dùng nhà cung cấp và mô hình đã được phê duyệt theo yêu cầu về dữ liệu, bảo mật và chi phí của công ty; xác nhận mô hình có thể đọc những loại tệp nhóm bạn xử lý. Nếu chưa rõ tình trạng phê duyệt hoặc khả năng của mô hình, hãy hỏi quản trị viên AI/CNTT trước khi thêm khóa hoặc đổi nhà cung cấp mặc định.
Nhập API key cho nhà cung cấp¶
Nhà cung cấp tạo sẵn đã có mô hình và điểm truy cập được cấu hình. Trước khi dùng, hãy xác nhận mô hình được phép xử lý tài liệu của bạn và có thể đọc loại tệp tương ứng; cũng cần API key để kiểm tra kết nối thành công.
Mở dòng OpenAI, bật Default Provider (Nhà cung cấp mặc định) cho ví dụ này rồi điền API Key bằng thông tin xác thực nhận qua quy trình quản lý bí mật đã được công ty phê duyệt. Sau khi lưu, trường này chỉ hiện các dấu chấm che ký tự; Viindoo không hiển thị lại khóa đã lưu.
Ghi chú
API Base URL (URL gốc của API) không hiện với OpenAI vì nhà cung cấp này dùng điểm truy cập đã cấu hình. Trường này có ở Ollama (Local) và Custom (OpenAI-compatible), nơi điểm truy cập phụ thuộc môi trường của bạn.
Mẹo
Hoàn thành bước này khi: trường API Key hiển thị dấu chấm che ký tự thay vì để trống và biểu mẫu đã được lưu.
Kiểm tra kết nối¶
Khóa đã lưu vẫn có thể sai vì thừa khoảng trắng, sao chép từ dự án khác hoặc đã bị thu hồi. Kiểm tra ngay giúp phát hiện vấn đề trước khi bộ phận Vận hành hoặc Kinh doanh gặp lỗi giữa lúc xử lý một Shipping Instruction thực tế.
Bấm Test Connection (Kiểm tra kết nối) ở đầu biểu mẫu nhà cung cấp.
Sau khi bấm, Viindoo gửi một yêu cầu tối thiểu đến nhà cung cấp và đọc phản hồi. Với khóa OpenAI đã cấu hình trong hướng dẫn này, thông báo hiển thị Connection Successful (Kết nối thành công) - "Provider 'OpenAI' is reachable and responding correctly." Nếu khóa sai hoặc điểm truy cập không hoạt động, hệ thống sẽ báo lỗi.
Mẹo
Hoàn thành bước này khi: xuất hiện thông báo màu xanh "Provider 'OpenAI' is reachable and responding correctly.", không phải thông báo lỗi.
Xác nhận các mẫu tài liệu giao nhận đã sẵn sàng¶
Các mẫu tài liệu giao nhận là dữ liệu do mô-đun tải khi cài, không cần tạo ở đây. Bước này chỉ xác nhận chúng đã được tải đầy đủ, vì nếu thiếu mẫu, bộ phận Vận hành không thể chọn đúng loại tài liệu khi dùng Điền booking hoặc lô hàng từ tài liệu bằng AI.
Vào .
Danh sách có năm dòng: Booking Confirmation, Shipping Instruction (FCL), Shipping Instruction (LCL), Bill of Lading (Ocean) và Arrival Notice. Kiểm tra cột Target Model (Mô hình đích): dòng đầu là Booking, bốn dòng còn lại là Logistics Shipment.
Xem thêm
Điền booking hoặc lô hàng từ tài liệu bằng AI - trình hướng dẫn đọc tài liệu bằng các mẫu này và nhà cung cấp bạn vừa cấu hình.
Mẹo
Thiết lập đúng khi: có đủ năm dòng, không dòng nào bị lưu trữ, và cột Target Model (Mô hình đích) hiển thị Booking hoặc Logistics Shipment đúng như trên.
Giới hạn hiện tại¶
Bước |
Viindoo hiện xử lý thế nào |
Cách bạn thực hiện |
|---|---|---|
Kiểm tra kết nối |
Một lỗi bố cục trên biểu mẫu đặt nút ở đầu biểu mẫu thay vì thanh nút thông thường; nút vẫn hoạt động |
Tìm Test Connection (Kiểm tra kết nối) ở đầu biểu mẫu nhà cung cấp, không phải trên thanh trạng thái |
Tạo nhà cung cấp Custom |
Không có bản ghi mẫu để sao chép; khác với sáu nhà cung cấp còn lại, Custom không được điền sẵn |
Tự điền tất cả trường, bắt đầu bằng API Base URL (URL gốc của API), trường bắt buộc đối với nhà cung cấp này |
Xử lý vướng mắc¶
"Unsupported provider" khi phân tích tài liệu¶
Hiện tượng: trình hướng dẫn Import from Document (Nhập từ tài liệu) hiển thị "Unsupported provider: ...".
Nguyên nhân: bản ghi nhà cung cấp có giá trị nằm ngoài bảy loại được hỗ trợ (OpenAI, Anthropic Claude, Google Gemini, Groq, OpenRouter, Ollama (Local), Custom); thường chỉ xảy ra khi giá trị được ghi bằng cách khác ngoài màn hình này, chẳng hạn qua nhập dữ liệu hoặc lệnh gọi API.
Cách xử lý:
Mở nhà cung cấp tại .
Chọn lại giá trị hợp lệ cho Provider (Nhà cung cấp) rồi lưu.
"Ollama requires an API Base URL..."¶
Hiện tượng: Test Connection hoặc Analyze Document thất bại và yêu cầu API Base URL.
Nguyên nhân: Provider (Nhà cung cấp) là Ollama (Local) nhưng API Base URL (URL gốc của API) còn trống. Ollama không có một địa chỉ chung cố định như nhà cung cấp đám mây.
Cách xử lý:
Nhập địa chỉ máy chủ Ollama vào API Base URL (URL gốc của API) (ví dụ
http://192.168.1.100:11434).Bấm lại Test Connection (Kiểm tra kết nối).
"Model '...' cannot read images or PDF pages"¶
Hiện tượng: phân tích PDF quét hoặc ảnh thất bại với thông báo này dù Test Connection đã thành công.
Nguyên nhân: mô hình gán cho nhà cung cấp có Vision Support (Hỗ trợ hình ảnh) là No. Test Connection chỉ kiểm tra nhà cung cấp có phản hồi, không kiểm tra khả năng đọc ảnh của mô hình.
Cách xử lý:
Vào và kiểm tra giá trị Vision Support (Hỗ trợ hình ảnh) của mô hình.
Thay bằng mô hình có Vision Support (Hỗ trợ hình ảnh) là Yes (với Ollama là
llavahoặcllama3.2-vision).