ZCode AI Cài đặt API tùy chỉnh

ZCode có thể thêm các dịch vụ triển khai giao thức Anthropic hoặc OpenAI làm Nhà cung cấp tùy chỉnh. Hướng dẫn này tuân theo thứ tự thực tế trong luồng Connect Models → Custom Providers (Anthropic / OpenAI Compatible) chính thức của TokenHub và định cấu hình TokenHub làm nhà cung cấp OpenAI-compatible tại https://us-api.tokenhub.com/v1.

Mở cài đặt mô hình

Trong lần khởi chạy đầu tiên, khi không có model nào, hãy chọn Use API Key. Nếu ZCode đã mở, hãy nhấp vào tên model trong hộp nhắc, chọn Manage Models và mở Settings → Model Settings.

Thêm nhà cung cấp tùy chỉnh TokenHub

Thực hiện theo bảy bước trong quy trình Nhà cung cấp tùy chỉnh của ZCode:

1. Mở Settings → Model Settings.
2. Ở cuối danh sách nhà cung cấp, nhấp vào Add Provider.
3. Đặt tên nhà cung cấp là TokenHub.
4. Chọn OpenAI-compatible. Trong menu Base URL, chọn địa chỉ tùy chỉnh hoặc nhập https://us-api.tokenhub.com/v1 theo cách thủ công.
5. Nhập khóa TokenHub API của bạn vào API Key.
6. Nhấp vào Add Model và nhập ID mẫu chính xác từ danh mục mẫu TokenHub. Thêm từng mô hình bổ sung riêng biệt.
7. Lưu cài đặt và bật công tắc Enable của nhà cung cấp. Xác nhận rằng mọi kiểu máy bạn định sử dụng cũng được bật.

ZCode không suy ra ID mẫu máy của bên thứ ba cho bạn. Nếu nhà cung cấp không trả về danh sách kiểu máy, hãy thêm từng ID chính xác theo cách thủ công bằng Add Model.

Không kết hợp cài đặt giao thức Anthropic và OpenAI trong một nhà cung cấp. Tạo một nhà cung cấp riêng cho Anthropic Messages và sử dụng URL gốc theo yêu cầu của giao thức đó.

Định cấu hình cài đặt nâng cao cho một kiểu máy

Trong Settings → Model Providers, mở mô hình bạn đã thêm và mở rộng Advanced:

• Max output tokens: thường để trống phần này và để dịch vụ mô hình báo cáo giá trị được hỗ trợ. Chỉ đặt thủ công sau khi xác nhận giới hạn của mẫu đích.
• Context window: điều này có thể chỉnh sửa được đối với các mô hình Nhà cung cấp tùy chỉnh và giá trị đã lưu chỉ áp dụng cho các cuộc hội thoại mới. Sử dụng thông số kỹ thuật của mẫu TokenHub, không phải giá trị từ mẫu khác.
• Các mức hiển thị của Thinking effort: tùy thuộc vào kiểu máy và giao thức. Yêu cầu OpenAI-compatible sử dụng reasoning_effort; việc triển khai của bên thứ ba có thể từ chối một số cấp độ được hiển thị bởi ZCode. Hạ mức hoặc tắt tùy chọn sau khi xảy ra lỗi tham số 400.
• Custom request parameters: ZCode không tự động đưa các giá trị tùy ý được thêm thủ công vào nhà cung cấp địa phương options vào nội dung yêu cầu. Đừng dựa vào việc chỉnh sửa ~/.zcode/v2/config.json để thêm các thông số lý luận hoặc hình ảnh bổ sung.

Cách ZCode quyết định xem đầu vào hình ảnh có khả dụng hay không

ZCode kết hợp nhà cung cấp, ID mẫu, khả năng danh mục mô hình và giao thức hoạt động khi xử lý hình ảnh:

• Khi biết sự hỗ trợ, ZCode sẽ giữ hình ảnh và gửi nó đến dịch vụ mô hình.
• Khi mô hình được đánh dấu là không được hỗ trợ, ZCode sẽ xóa hình ảnh và thay thế bằng thông báo văn bản.
• Khi không xác định được khả năng, ZCode không chặn hình ảnh trước; TokenHub đưa ra quyết định cuối cùng và có thể từ chối yêu cầu.

Cùng một mô hình có thể được xử lý khác nhau thông qua nhà cung cấp hoặc giao thức khác. Trước tiên, hãy kiểm tra văn bản và chỉ gửi hình ảnh khi trang mẫu TokenHub liệt kê rõ ràng hình ảnh đầu vào.

Chọn mô hình và xác minh

1. Quay lại bộ chọn mô hình trong hộp nhắc.
2. Chọn nhà cung cấp TokenHub và kiểu máy bạn đã thêm.
3. Gửi một hướng dẫn ngắn gọn như “Giải thích tệp hiện tại mà không sửa đổi nó”.
4. Trong nhật ký yêu cầu TokenHub, hãy xác nhận rằng yêu cầu sử dụng /v1/chat/completions và xác minh ID mẫu, mã trạng thái và mức sử dụng.
5. Sau khi phản hồi văn bản ổn định, hãy thử chỉnh sửa, gọi công cụ, ngữ cảnh dài và nhập hình ảnh riêng biệt.

Điều này tuân theo hướng dẫn Verify The Setup chính thức của ZCode: chọn kênh mới, gửi hướng dẫn kiểm tra ngắn và xác nhận phản hồi ổn định trước khi hoạt động thực sự.

Phạm vi của proxy HTTP tích hợp của ZCode

Proxy HTTP được định cấu hình trong ZCode Settings bao gồm API mô hình, MCP, WebFetch, quy trình con đầu cuối, thị trường tiện ích mở rộng và tải trang trong ứng dụng. Nó không bao gồm đăng nhập tài khoản máy tính để bàn, tạo Wiki, WebSocket điều khiển từ xa trên web hoặc kết nối từ xa SSH. ZCode cũng không định tuyến mọi yêu cầu thông qua các biến HTTP_PROXY / HTTPS_PROXY của hệ thống theo mặc định. Khởi động lại ZCode sau khi thay đổi proxy trong ứng dụng.

Khắc phục sự cố

• Thiếu mô hình: đảm bảo cả nhà cung cấp và mô hình đều được bật.
• 404: xác nhận điểm cuối không lặp lại /chat/completions.
• Định dạng yêu cầu không khớp: kiểm tra xem nhà cung cấp là OpenAI-compatible hay Anthropic.
• Văn bản hoạt động nhưng tính năng chỉnh sửa mã thì không: mô hình đã chọn có thể không có lệnh gọi công cụ gốc đáng tin cậy.
• Nỗ lực suy nghĩ trả về 400: hạ thấp hoặc vô hiệu hóa cấp độ vì việc triển khai có thể không chấp nhận.
• Yêu cầu hình ảnh không thành công: hãy sử dụng ID mẫu chuẩn và xác nhận nhà cung cấp, giao thức và mẫu TokenHub đều hỗ trợ hình ảnh.
• Thay đổi proxy không có hiệu lực: khởi động lại ZCode và xác nhận rằng loại lưu lượng truy cập được bao phủ bởi proxy tích hợp của ZCode.

Tài liệu tham khảo chính thức

• ZCode: Kết nối các mô hình