Trang này được dịch từ tài liệu tiếng Anh. Lệnh, định danh và ví dụ giữ nguyên. Runtime 7.24.4 · SDK 2.6.7. Bản tiếng Anh

Nhà cung cấp tùy chỉnh và cổng kết nối

Trạng thái: Đang hoạt động Phạm vi: trạng thái hiện tại Xem xét lần cuối: 2026-09-06 Chủ sở hữu: môi trường chạy ax-code

AX Code nói chuyện với mô hình qua các giao thức nhà cung cấp chuẩn. Mọi endpoint nói API tương thích OpenAI (/v1/chat/completions) hoặc tương thích Anthropic (/v1/messages) đều có thể được thêm làm nhà cung cấp tùy chỉnh bằng cách trỏ baseURL tới đó — không sửa mã và không chờ một mẫu dựng sẵn.

Điều này bao gồm bộ tổng hợp tự lưu trữ và cổng chuyển tiếp như LiteLLM, one-api, new-api và Vercel AI Gateway, cũng như proxy doanh nghiệp riêng và mọi dịch vụ tương thích khác. AX Code đối xử với chúng một cách thống nhất: nó nói giao thức trên dây, bạn cung cấp URL và khóa.

Ghi chú trách nhiệm. Một cổng kết nối đứng giữa AX Code và mô hình thượng nguồn, nên lời nhắc, mã và thông tin xác thực của bạn đi qua nó. Khi bạn trỏ AX Code tới một chuyển tiếp bên thứ ba hoặc gộp tài khoản, bạn chịu trách nhiệm tin tưởng nhà vận hành đó với dữ liệu của mình và ở trong điều khoản dịch vụ của mọi nhà cung cấp thượng nguồn mà nó định tuyến tới. Các mẫu cổng dựng sẵn như OpenRouter dùng cùng đường giao thức chuẩn; cấu hình cổng tùy chỉnh không có nghĩa là bảo chứng cho bất kỳ nhà vận hành chuyển tiếp nào.

Thiết lập tương tác

Dùng /connect -> Nhà cung cấp API đám mây -> Nhà cung cấp API tùy chỉnh cho một cổng tương thích, hoặc /connect -> AX Trust -> Kết nối AX Trust cho một cổng AX Trust. Nhập URL gốc của nó (gồm /v1 cho AX Trust) và khóa API máy khách. Trình soạn khám phá ID mô hình cùng siêu dữ liệu và lưu thông tin xác thực trong kho xác thực đã mã hóa. Nó cũng có thể nhận ID mô hình tường minh nếu khám phá không sẵn có. Kết nối lại một URL đã lưu giữ ID nhà cung cấp và khóa khi token được để trống. Kết nối AX Trust giữ danh mục của chúng sau các lần sửa và làm mới mô hình. AX Code gửi X-AX-Prompt-Cache-Key với ID phiên trên các kết nối đó để cổng có thể giữ một phiên trên một tài khoản đủ điều kiện; đặt provider.<id>.options.axTrust thành false để tắt nó. Tiêu đề này không được chuyển tiếp thượng nguồn và không phải một thân prompt_cache_key.

Các nhà cung cấp AX Trust đã kết nối làm mới danh sách mô hình ở nền khi khởi động. AX Code gọi GET /models của endpoint đã cấu hình với thông tin xác thực sẵn có và cập nhật tên mô hình, giới hạn ngữ cảnh/đầu ra, suy luận, gọi công cụ, hỗ trợ nhiệt độ và hỗ trợ ảnh. Mô hình có khả năng ảnh hiện dấu thị giác trong /models, gồm bí danh cổng khi AX Trust quảng bá hỗ trợ ảnh của chúng. TUI cập nhật khi khám phá hoàn tất. Với đúng ID mô hình DeepSeek bên thứ nhất, siêu dữ liệu thiếu được điền từ danh mục models.dev đóng gói. Cờ khả năng và giới hạn cổng tường minh được ưu tiên; bí danh không xác định không kế thừa khả năng theo độ giống tên.

Một lần làm mới thành công thay danh sách môi trường chạy, gỡ các mô hình không còn được cổng quảng bá, và vẫn áp dụng danh sách cho phép/chặn đã cấu hình. Hết thời gian, lỗi, phản hồi rỗng hoặc không hợp lệ giữ danh sách đã lưu và ghi một lỗi khám phá. Khởi động không chờ mạng. Lần làm mới này không viết lại cấu hình nhà cung cấp hay thông tin xác thực; cấu hình đã lưu vẫn là phương án dự phòng khi khởi động. Nhà cung cấp API tùy chỉnh thông thường giữ làm mới thủ công.

Cách một nhà cung cấp được phân giải

Với mỗi yêu cầu, AX Code cần ba thứ từ một mục nhà cung cấp:

npm — bộ chuyển đổi AI SDK nói giao thức trên dây. Dùng @ai-sdk/openai-compatible cho endpoint kiểu OpenAI và @ai-sdk/anthropic cho endpoint kiểu Anthropic. Chỉ các bộ chuyển đổi @ai-sdk/* được đóng gói hoặc cài được.
options.baseURL — URL cổng. Quay về trường api của nhà cung cấp, rồi tới api.url của chính mô hình. Hỗ trợ thay thế ${ENV_VAR}.
Một thông tin xác thực — được phân giải theo thứ tự từ options.apiKey, rồi kho xác thực đã lưu, rồi các biến env của nhà cung cấp.

Cấu hình thủ công cũng cần một bản đồ models tường minh. Trình soạn tương tác điền bản đồ này từ endpoint hoặc từ các ID mô hình bạn cung cấp.

Các đám mây GPU riêng chuyên biệt là nhà cung cấp hạng nhất dưới /connect → Đám mây GPU riêng. Dán URL tương thích OpenAI và token (alibaba-pai, runpod, huggingface-endpoints, sagemaker, volcengine-ark, modelarts, tencent-ti hoặc custom-private-gpu); AX Code gọi GET …/models và dùng các ID mô hình đã triển khai một cách tự động.

Các danh mục GPU được lưu trữ (nebius, fireworks-ai, togetherai, baseten, nvidia, deepinfra) dùng một khóa API và ảnh chụp mô hình đóng gói, cùng mẫu mà OpenCode dùng.

Cổng tương thích OpenAI

Hầu hết bộ tổng hợp (LiteLLM, one-api, new-api, cổng miễn phí hoặc tự lưu trữ) phơi bày một bề mặt tương thích OpenAI. Thêm mục này vào ax-code.json của bạn (toàn cục tại ~/.config/ax-code/ax-code.json, hoặc theo dự án ở gốc kho):

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-gateway": {
      "name": "My Gateway",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://gateway.example.com/v1",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o (via gateway)",
          "tool_call": true,
          "reasoning": false,
          "attachment": true,
          "limit": { "context": 128000, "output": 16384 },
        },
      },
    },
  },
}

Khóa "my-gateway" là id nhà cung cấp bạn chọn trong /connect và ax-code models.
Mỗi khóa dưới models là ID lựa chọn cục bộ. Đặt id của mục thành đúng ID mô hình mà cổng kỳ vọng khi nó khác khóa đó; nếu không, khóa được dùng cho các mô hình khai báo thủ công mà không có ánh xạ danh mục sẵn có.
Ưu tiên ${ENV_VAR} hơn một khóa nguyên văn để bí mật không nằm trong cấu hình đã commit.

Bí danh mô hình của cổng sau khi đổi endpoint

Đổi options.baseURL không dịch các ID mô hình đã cấu hình thủ công. Ví dụ, một endpoint AX Trust có thể quảng bá deepseek-flash trong khi một lựa chọn cục bộ sẵn có là ax-trust/deepseek-v4-flash. Hãy giữ khóa cục bộ và đặt provider.ax-trust.models.deepseek-v4-flash.id thành deepseek-flash. AX Code khi đó gửi ID cổng trong các yêu cầu API.

Xem ví dụ cấu hình AX Trust DeepSeek Flash. Hợp nhất các trường nhà cung cấp liên quan vào cấu hình sẵn có của bạn, giữ các mô hình khác và cài đặt khả năng của chúng. Ví dụ dùng {env:AX_TRUST_API_KEY}; hãy đặt biến môi trường đó trước khi khởi động AX Code, hoặc giữ cấu hình thông tin xác thực sẵn có. Khởi động lại AX Code sau khi sửa.

Khi chẩn đoán 403 model is not allowed, hãy so sánh ID mô hình của yêu cầu với phản hồi GET /models đã xác thực của endpoint. Riêng một yêu cầu danh sách mô hình thành công không thiết lập quyền chạy một mô hình. Nếu đúng ID vẫn thất bại, hãy kiểm tra quyền khóa/mô hình của cổng.

Cổng tương thích Anthropic

Các chuyển tiếp phơi bày /v1/messages (dạng API Claude) dùng bộ chuyển đổi Anthropic:

{
  "$schema": "https://ax-code.app/docs-assets/schema/config.schema.json",
  "provider": {
    "my-claude-gateway": {
      "name": "My Claude Gateway",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "baseURL": "https://gateway.example.com",
        "apiKey": "${MY_GATEWAY_API_KEY}",
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet (via gateway)",
          "tool_call": true,
          "reasoning": true,
          "attachment": true,
          "limit": { "context": 200000, "output": 64000 },
        },
      },
    },
  },
}

Một số chuyển tiếp dạng Anthropic cũng tôn trọng trực tiếp các biến môi trường Claude. Để chạy không tương tác nhanh mà không sửa cấu hình, bạn có thể đặt:

export ANTHROPIC_BASE_URL="https://gateway.example.com"
export ANTHROPIC_AUTH_TOKEN="sk-..."

Một mục cấu hình vẫn được khuyến nghị khi bạn muốn cổng xuất hiện như nhà cung cấp có thể chọn riêng, với một danh sách mô hình đã chọn lọc.

Trường mô hình

Các mục mô hình dùng lại lược đồ sổ đăng ký; với một endpoint tùy chỉnh, các trường hữu ích là:

Trường	Ý nghĩa
`name`	Nhãn hiển thị trong bộ chọn mô hình
`tool_call`	Mô hình có hỗ trợ gọi công cụ/hàm hay không (cần cho công cụ)
`reasoning`	Mô hình có phát suy luận mở rộng hay không
`attachment`	Mô hình có nhận tệp đính kèm ảnh/tệp hay không
`limit`	Giới hạn token `{ context, output }` dùng để lập ngân sách
`modalities`	Các mảng `{ input, output }` tùy chọn (`text`, `image`, `pdf`, …)

Hãy đặt cờ khả năng khớp với những gì mô hình thượng nguồn thực sự hỗ trợ; AX Code dùng chúng để kiểm soát lời gọi công cụ, tệp đính kèm và ngân sách ngữ cảnh.

Xác minh

Sau khi lưu cấu hình:

ax-code models liệt kê mọi mô hình mà nhà cung cấp của bạn phơi bày.
/connect bên trong TUI hiện nhà cung cấp và cho bạn xác thực nếu bạn dùng khóa env thay vì options.apiKey.

Nếu thiếu một mô hình, hãy xác nhận id nhà cung cấp, khóa mô hình, và cổng có tới được tại baseURL hay không.

Xử lý sự cố

Lỗi xác thực — xác nhận thứ tự phân giải thông tin xác thực: options.apiKey thắng, nếu không thì dùng khóa env hoặc kho xác thực.
Luồng bị dừng — cổng đôi khi đệm SSE. Chỉnh options.chunkTimeout (theo từng khối) và options.timeout (cả yêu cầu) trên nhà cung cấp.
Lời gọi công cụ bị từ chối — đặt "tool_call": true trên mô hình và xác nhận mô hình thượng nguồn phía sau cổng thực sự hỗ trợ công cụ.