> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Khả năng tương thích của IDE & SDK
> Hướng dẫn tương thích dựa trên bằng chứng cho các công cụ lập trình AI, SDK và framework
## Tổng quan
TokenLab cung cấp nhiều định dạng API để các công cụ lập trình, SDK và framework phổ biến có thể tích hợp với lượng mã kết nối (glue code) tối thiểu.
Trang này được thiết kế có chủ đích để tập trung hơn so với một ma trận tiếp thị:
* **Được hỗ trợ (Supported)**: Nghĩa là chúng tôi cung cấp tài liệu về lộ trình thiết lập cụ thể và TokenLab cung cấp cấu trúc giao thức mà lộ trình đó yêu cầu.
* **Lộ trình native mạnh mẽ (Strong native path)**: Nghĩa là kho lưu trữ cũng có bằng chứng về bộ điều hợp (adapter) trực tiếp hoặc định dạng yêu cầu cho họ giao thức đó.
* **Nỗ lực tốt nhất (Best-effort)**: Nghĩa là việc tích hợp có thể hoạt động, nhưng client thượng nguồn không coi quy trình gateway tùy chỉnh này là một hợp đồng ổn định.
Các trường không được hỗ trợ không được xử lý đồng nhất. Trên các lộ trình tương thích, một số trường bị bỏ qua hoặc được chuẩn hóa. Trên `/v1/responses`, các trường không được hỗ trợ có thể trả về lỗi `400` hoặc `503` rõ ràng khi lộ trình đó không thể đảm bảo hành vi được yêu cầu.
## Các định dạng API được hỗ trợ
| Endpoint | Định dạng | Trường hợp sử dụng |
| --------------------------------------- | ------------------ | ---------------------------------- |
| `/v1/chat/completions` | OpenAI Chat | Tương thích phổ quát |
| `/v1/responses` | OpenAI Responses | Hội thoại có trạng thái (Stateful) |
| `/v1/messages` | Anthropic Messages | Các tính năng native của Claude |
| `/v1beta/models/:model:generateContent` | Google Gemini | Các tính năng native của Gemini |
## Khả năng tương thích của IDE & CLI
### Các lộ trình công cụ đã được ghi nhận
| Công cụ | Mức độ hỗ trợ | Định dạng | Ghi chú |
| ------------------- | ----------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Cursor** | Được hỗ trợ với giới hạn | Tương thích OpenAI | Hoạt động cho các luồng chat/editor tiêu chuẩn BYOK, không thay thế cho các tính năng do Cursor quản lý như Tab Completion |
| **Claude Code CLI** | Lộ trình native mạnh mẽ | Anthropic | Lộ trình `/v1/messages` native với phạm vi bao phủ bộ điều hợp cho thinking và `tool_choice` |
| **Codex CLI** | Được hỗ trợ với giới hạn mô hình/lộ trình | OpenAI Responses | Coi `/v1/responses` là lộ trình nâng cao cho các quy trình làm việc cụ thể của Codex; một số trường chỉ dành cho Responses không được đảm bảo trên mọi mô hình và lộ trình |
| **Gemini CLI** | Nỗ lực tốt nhất / thử nghiệm | Gemini | Luồng URL cơ sở TokenLab tùy chỉnh không phải là tích hợp Gemini CLI chính thức |
| **OpenCode** | Được hỗ trợ | Tương thích OpenAI | Sử dụng nhà cung cấp tương thích OpenAI theo mặc định; chỉ chuyển sang nhà cung cấp dựa trên Responses khi bạn thực sự cần |
| **OpenHands** | Được hỗ trợ | Tương thích OpenAI | Sử dụng lộ trình LiteLLM/tương thích OpenAI với `openai/` và URL cơ sở `/v1` của TokenLab |
Các trình soạn thảo và công cụ agent tương thích OpenAI khác thường hoạt động với cùng mẫu URL cơ sở; hãy kiểm tra hỗ trợ nhà cung cấp tùy chỉnh của chính công cụ đó trước khi sử dụng trong môi trường production.
### Ví dụ cấu hình
```
Base URL: https://api.tokenlab.sh/v1
API Key: sk-your-tokenlab-key
```
Cursor sử dụng định dạng công cụ kiểu Anthropic ở bên trong. TokenLab hỗ trợ cả hai:
* Định dạng OpenAI: `{ type: "function", function: { name, parameters } }`
* Định dạng Anthropic: `{ name, input_schema }` (không có trường type)
```bash theme={null}
export ANTHROPIC_BASE_URL="https://api.tokenlab.sh"
export ANTHROPIC_API_KEY="sk-your-tokenlab-key"
```
```bash theme={null}
export OPENAI_API_KEY="sk-your-tokenlab-key"
export LOCAL_ENDPOINT="https://api.tokenlab.sh/v1"
```
```bash theme={null}
export OPENAI_API_KEY="sk-your-tokenlab-key"
export OPENAI_BASE_URL="https://api.tokenlab.sh/v1"
aider --model gpt-5.4
```
## Khả năng tương thích của SDK
### Các lộ trình SDK & Framework đã được ghi nhận
| SDK / Framework | Ngôn ngữ | Mức độ hỗ trợ | Ghi chú |
| -------------------------------------------------------- | ----------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **OpenAI SDK** | Python/JS/Go | Lộ trình cốt lõi được hỗ trợ | Lộ trình tương thích cho Chat Completions và Embeddings `/v1`; sử dụng các lộ trình nhà cung cấp native cho hành vi cụ thể của nhà cung cấp, và không giả định các trường chỉ dành cho Responses hoạt động trên mọi mô hình |
| **Anthropic SDK** | Python/JS | Lộ trình native mạnh mẽ | Lộ trình Messages native với bằng chứng trực tiếp cho tools, thinking và prompt caching |
| **Vercel AI SDK** | TypeScript | Mẫu tích hợp được khuyến nghị | Ưu tiên `@ai-sdk/openai-compatible`; chỉ sử dụng `@ai-sdk/openai` khi bạn thực sự muốn hành vi native của Responses |
| **LangChain** | Python/JS | Các bề mặt tiêu chuẩn được hỗ trợ | `ChatOpenAI` và `OpenAIEmbeddings` là phạm vi dự kiến; các tính năng bổ sung native của nhà cung cấp nằm ngoài phạm vi |
| **LlamaIndex** | Python | Được hỗ trợ qua `OpenAILike` | Sử dụng `OpenAILike`, không phải các lớp OpenAI tích hợp sẵn, cho các gateway bên thứ ba như TokenLab |
| **OpenAI Agents SDK** | Python | Lộ trình chat-completions được hỗ trợ | Sử dụng `AsyncOpenAI(base_url="https://api.tokenlab.sh/v1")` với `OpenAIChatCompletionsModel`; hành vi Responses native phụ thuộc vào mô hình và lộ trình được chọn |
| **AutoGen** | Python | Lộ trình endpoint tùy chỉnh được hỗ trợ | Sử dụng `OpenAIChatCompletionClient` với `base_url: https://api.tokenlab.sh/v1` |
| **Semantic Kernel** | .NET | Lộ trình endpoint tùy chỉnh được hỗ trợ | Sử dụng endpoint tùy chỉnh của trình kết nối hoàn thiện chat OpenAI và trỏ nó đến `https://api.tokenlab.sh/v1` |
| **CrewAI** | Python | Lộ trình endpoint tùy chỉnh được hỗ trợ | Đặt `OPENAI_API_BASE` hoặc `LLM(base_url=...)` thành endpoint `/v1` của TokenLab |
| **Pydantic AI** | Python | Lộ trình nhà cung cấp tương thích OpenAI được hỗ trợ | Sử dụng `OpenAIChatModel` với `OpenAIProvider(base_url="https://api.tokenlab.sh/v1")` |
| **DSPy** | Python | Lộ trình endpoint tùy chỉnh được hỗ trợ | Sử dụng `dspy.LM("openai/", api_base="https://api.tokenlab.sh/v1")` |
| **Langflow** | Python / Web | Được hỗ trợ với giới hạn phạm vi | Sử dụng trường **OpenAI API Base** của thành phần OpenAI với endpoint `/v1` của TokenLab |
| **Haystack** | Python | Lộ trình endpoint tùy chỉnh được hỗ trợ | Sử dụng `OpenAIChatGenerator(api_base_url="https://api.tokenlab.sh/v1")` |
| **Graphiti** | Python | Lộ trình endpoint tùy chỉnh được hỗ trợ | Sử dụng `OpenAIGenericClient` với endpoint `/v1` của TokenLab |
| **Dify** | - | Được hỗ trợ với giới hạn phạm vi | Nhà cung cấp OpenAI và các luồng hướng chat-completions là lộ trình dự kiến; không phù hợp cho các hành vi Responses hoặc WebSocket cụ thể của Codex |
| **Flowise** | Web / Node | Được hỗ trợ với giới hạn phạm vi | Sử dụng node chat TokenLab khi có sẵn, hoặc node tương thích ChatOpenAI trỏ đến `https://api.tokenlab.sh/v1` |
| **Mem0** | Python | Lộ trình endpoint tùy chỉnh được hỗ trợ | Giữ nhà cung cấp OpenAI và đặt `openai_base_url` thành endpoint `/v1` của TokenLab |
| **Agno** | Python | Lộ trình được hỗ trợ | Sử dụng trình bao bọc mô hình TokenLab khi có sẵn, hoặc lộ trình URL cơ sở tương thích OpenAI |
| **Browser Use** | Python | Lộ trình endpoint tùy chỉnh được hỗ trợ | Sử dụng `ChatOpenAILike` với endpoint `/v1` của TokenLab |
| **VoltAgent** | TypeScript | Lộ trình endpoint tùy chỉnh được hỗ trợ | Truyền nhà cung cấp OpenAI của AI SDK được cấu hình với `baseURL: "https://api.tokenlab.sh/v1"` |
| **Ragas** | Python | Lộ trình endpoint tùy chỉnh được hỗ trợ | Truyền `AsyncOpenAI(base_url="https://api.tokenlab.sh/v1")` vào `llm_factory` |
| **Guardrails** | Python | Lộ trình xác thực được hỗ trợ | Truyền một callable chat completions của OpenAI SDK được cấu hình với endpoint `/v1` của TokenLab |
| **Prompt flow** | Python / CLI | Lộ trình endpoint tùy chỉnh được hỗ trợ | Tạo kết nối OpenAI với `base_url=https://api.tokenlab.sh/v1` |
| **Promptfoo** | CLI / Node | Lộ trình được hỗ trợ | Sử dụng các nhà cung cấp chat hoặc Responses của OpenAI với `apiBaseUrl: https://api.tokenlab.sh/v1` |
| **Portkey Gateway** | Gateway | Lộ trình được hỗ trợ | Sử dụng TokenLab làm nhà cung cấp thượng nguồn cho lưu lượng chat và Responses tương thích OpenAI |
| **Helicone** | Gateway / Observability | Lộ trình quan sát được hỗ trợ | Định tuyến các yêu cầu tương thích OpenAI qua Helicone Gateway với `Helicone-Target-Url: https://api.tokenlab.sh` |
| **Langfuse** | Observability | Lộ trình theo dõi được hỗ trợ | Cấu hình tích hợp OpenAI của Langfuse với URL cơ sở `/v1` của TokenLab |
| **OpenLIT** | Observability | Lộ trình theo dõi được hỗ trợ | Instrument một client OpenAI SDK được cấu hình với URL cơ sở `/v1` của TokenLab |
| **OpenLLMetry** | Observability | Lộ trình theo dõi được hỗ trợ | Sử dụng instrumentation của OpenAI SDK với URL cơ sở `/v1` của TokenLab |
| **Phoenix** | Observability | Lộ trình theo dõi được hỗ trợ | Tự động instrument client OpenAI SDK được cấu hình với URL cơ sở `/v1` của TokenLab |
| **Opik** | Observability | Lộ trình theo dõi được hỗ trợ | Wrap một client OpenAI SDK được cấu hình với URL cơ sở `/v1` của TokenLab |
| **LangBot** | Bot Platform | Lộ trình chat được hỗ trợ | Sử dụng requester TokenLab khi có sẵn, hoặc cấu hình requester tương thích OpenAI với endpoint `/v1` của TokenLab |
| **Open WebUI** | Web Chat | Lộ trình ứng dụng chat được hỗ trợ | Thêm TokenLab làm kết nối API tương thích OpenAI và làm mới danh sách mô hình |
| **Chatbox / DeepChat / Jan / LibreChat / Cherry Studio** | Desktop / Web | Lộ trình ứng dụng chat được hỗ trợ | Sử dụng luồng nhà cung cấp tùy chỉnh tương thích OpenAI của mỗi ứng dụng; các ứng dụng này thường hướng đến chat-completions |
## Các tham số Chat Completions
### Các tham số cốt lõi
| Tham số | Loại | Mô tả |
| ------------- | ------- | ----------------------------- |
| `model` | string | Định danh mô hình (bắt buộc) |
| `messages` | array | Tin nhắn hội thoại (bắt buộc) |
| `max_tokens` | integer | Số token đầu ra tối đa |
| `temperature` | number | Nhiệt độ lấy mẫu (0-2) |
| `top_p` | number | Lấy mẫu Nucleus (0-1) |
| `stream` | boolean | Bật streaming |
### Gọi công cụ (Tool Calling)
```json theme={null}
{
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get weather for a location",
"parameters": {
"type": "object",
"properties": {
"location": { "type": "string" }
}
},
"strict": true
}
}
],
"tool_choice": "auto",
"parallel_tool_calls": true
}
```
### Tùy chọn Tool Choice
| Định dạng | Ví dụ | Mô tả |
| ------------------- | --------------------------------------------------------------------- | ------------------------------ |
| String | `"auto"`, `"none"`, `"required"` | Lựa chọn đơn giản |
| Đối tượng OpenAI | `{ "type": "function", "function": { "name": "fn" } }` | Ép buộc hàm cụ thể |
| Đối tượng Anthropic | `{ "type": "tool", "name": "fn", "disable_parallel_tool_use": true }` | Định dạng native của Anthropic |
### Các tham số nâng cao
| Tham số | Loại | Mô tả |
| ------------------- | ------------ | ------------------------------------------------------------------------ |
| `stream_options` | object | Chỉ Chat Completions: `{ include_usage: true }` để đếm token |
| `reasoning_effort` | string | `"low"`, `"medium"`, `"high"` cho các mô hình GPT-5 có khả năng suy luận |
| `service_tier` | string | `"auto"` hoặc `"default"` |
| `seed` | integer | Đầu ra tất định |
| `logprobs` | boolean | Trả về xác suất log |
| `top_logprobs` | integer | Số lượng logprobs hàng đầu (0-20) |
| `logit_bias` | object | Bản đồ thiên kiến token (-100 đến 100) |
| `frequency_penalty` | number | Phạt lặp lại (-2 đến 2) |
| `presence_penalty` | number | Phạt chủ đề (-2 đến 2) |
| `stop` | string/array | Chuỗi dừng |
| `n` | integer | Số lượng hoàn thiện (1-128) |
| `user` | string | Định danh người dùng để theo dõi |
### Các tính năng nâng cao của OpenAI
| Tham số | Loại | Mô tả |
| ------------ | ------- | ----------------------------------------------- |
| `modalities` | array | `["text", "audio"]` cho đa phương thức |
| `audio` | object | Cấu hình đầu ra âm thanh (giọng nói, định dạng) |
| `prediction` | object | Đầu ra dự đoán để hoàn thiện nhanh hơn |
| `metadata` | object | Cặp khóa-giá trị để theo dõi |
| `store` | boolean | Lưu trữ để truy xuất sau |
### Các tùy chọn cụ thể của nhà cung cấp
```json theme={null}
{
"anthropic_options": {
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"prompt_caching": true
},
"google_options": {
"safety_settings": [...],
"google_search": true,
"code_execution": true
}
}
```
## Các tham số Anthropic Messages
### Các tham số cốt lõi
| Tham số | Loại | Mô tả |
| ------------ | ------------ | ------------------------------ |
| `model` | string | Định danh mô hình |
| `messages` | array | Tin nhắn hội thoại |
| `max_tokens` | integer | Đầu ra tối đa (lên đến 128000) |
| `system` | string/array | System prompt |
| `stream` | boolean | Bật streaming |
### Gọi công cụ (Tool Calling)
```json theme={null}
{
"tools": [
{
"name": "get_weather",
"description": "Get weather",
"input_schema": {
"type": "object",
"properties": {
"location": { "type": "string" }
}
}
}
],
"tool_choice": {
"type": "auto",
"disable_parallel_tool_use": false
}
}
```
### Suy luận mở rộng (Extended Thinking)
```json theme={null}
{
"model": "claude-opus-4-6",
"thinking": {
"type": "enabled",
"budget_tokens": 10000
}
}
```
## Các tham số Responses API
### Các tham số cốt lõi
| Tham số | Loại | Mô tả |
| ---------------------- | ------------ | ---------------------- |
| `model` | string | Định danh mô hình |
| `input` | string/array | Nội dung đầu vào |
| `instructions` | string | Hướng dẫn hệ thống |
| `max_output_tokens` | integer | Số token đầu ra tối đa |
| `previous_response_id` | string | Tiếp tục hội thoại |
### Các tham số nâng cao
| Tham số | Loại | Mô tả |
| --------------------- | ------ | --------------------------------- |
| `truncation_strategy` | string | `"auto"` hoặc `"disabled"` |
| `include` | array | `["reasoning.encrypted_content"]` |
| `reasoning_effort` | string | Cho các mô hình suy luận |
| `service_tier` | string | Cấp độ ưu tiên |
### Định dạng công cụ
Hỗ trợ cả định dạng công cụ OpenAI và Anthropic:
```json theme={null}
// Định dạng OpenAI
{ "type": "function", "name": "fn", "parameters": {...} }
// Định dạng Anthropic (tương thích Cursor)
{ "name": "fn", "input_schema": {...} }
```
## Các tham số Gemini API
### Các tham số cốt lõi
| Tham số | Loại | Mô tả |
| ------------------- | ------ | -------------------- |
| `contents` | array | Nội dung hội thoại |
| `systemInstruction` | object | System prompt |
| `generationConfig` | object | Cài đặt tạo nội dung |
### Công cụ
```json theme={null}
{
"tools": [{
"functionDeclarations": [{
"name": "search",
"description": "Search the web",
"parameters": {...}
}],
"codeExecution": {},
"googleSearch": {}
}],
"toolConfig": {
"functionCallingConfig": {
"mode": "AUTO"
}
}
}
```
### Cài đặt an toàn (Safety Settings)
```json theme={null}
{
"safetySettings": [
{
"category": "HARM_CATEGORY_HARASSMENT",
"threshold": "BLOCK_MEDIUM_AND_ABOVE"
}
]
}
```
### Các tham số bổ sung
| Tham số | Loại | Mô tả |
| ------------------ | ------ | ---------------------------------------- |
| `cachedContent` | string | Tham chiếu nội dung đã lưu cache |
| `responseMimeType` | string | `"text/plain"` hoặc `"application/json"` |
| `responseSchema` | object | JSON schema cho đầu ra có cấu trúc |
## Streaming
Các endpoint tạo nội dung hỗ trợ `stream: true`, bao gồm Chat Completions và Responses, sử dụng Server-Sent Events (SSE):
```bash theme={null}
# Chat Completions
curl https://api.tokenlab.sh/v1/chat/completions \
-H "Authorization: Bearer sk-xxx" \
-d '{"model": "gpt-4o", "messages": [...], "stream": true}'
# Theo dõi sử dụng Chat Completions
-d '{"...", "stream_options": {"include_usage": true}}'
```
## Xử lý lỗi
TokenLab trả về các phản hồi lỗi tương thích với OpenAI:
```json theme={null}
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}
```
Xem [Hướng dẫn xử lý lỗi](/guides/error-handling) để biết thêm chi tiết.
## Các phương pháp tốt nhất
Các tham số không xác định chỉ được chuyển tiếp khi lộ trình công khai và mô hình được chọn hỗ trợ chúng.
Đối với streaming Chat Completions, hãy bật `stream_options.include_usage` để có số lượng token chính xác. Responses có hợp đồng streaming riêng và không cung cấp tùy chọn chỉ dành cho Chat này.
Khớp với định dạng dự kiến của SDK của bạn. TokenLab chấp nhận cả định dạng OpenAI và Anthropic.