Hướng Dẫn Chuyển Đổi Giao Thức

RouteAPI, với vai trò là cổng API thống nhất, tự động xử lý việc chuyển đổi giữa các định dạng giao thức khác nhau bên trong hệ thống. Khi bạn gọi mô hình Claude bằng giao thức OpenAI, hoặc gọi mô hình Gemini bằng giao thức Claude Messages, RouteAPI xử lý sự khác biệt trong cấu trúc tin nhắn, ánh xạ tham số và định dạng phản hồi, vì vậy bạn không cần quan tâm đến chi tiết giao thức cơ bản.

Tổng Quan Cơ Chế Chuyển Đổi

RouteAPI như Lớp Chuyển Đổi Giao Thức

RouteAPI hỗ trợ ba điểm vào giao thức chính:

Giao thức tương thích OpenAI: /v1/chat/completions, /v1/responses
Giao thức Claude Messages: /v1/messages
Giao thức Google Gemini: /v1beta/models/{model}:generateContent

Khi yêu cầu đến, RouteAPI xác định loại giao thức dựa trên đường dẫn, xác định upstream đích dựa trên ID mô hình, sau đó thực hiện các chuyển đổi định dạng cần thiết giữa chúng.

Khi Nào Cần Chuyển Đổi

Kịch Bản	Chuyển Đổi?	Mô Tả
Giao thức OpenAI → Mô hình OpenAI	Không	Chuyển tiếp trực tiếp
Claude Messages → Mô hình Claude	Không	Chuyển tiếp trực tiếp
Giao thức OpenAI → Mô hình Claude	Có	OpenAI → Claude Messages
Giao thức OpenAI → Mô hình Gemini	Có	OpenAI → Gemini contents
Claude Messages → Mô hình OpenAI	Có	Claude Messages → OpenAI
Claude Messages → Mô hình Gemini	Có	Claude Messages → Gemini

Tính Minh Bạch của Chuyển Đổi

Chuyển đổi giao thức minh bạch với khách hàng. Bạn gửi yêu cầu định dạng OpenAI và nhận phản hồi định dạng OpenAI, ngay cả khi Claude hoặc Gemini được gọi bên dưới.

Tuy nhiên, chuyển đổi có giới hạn:

Các tham số không được giao thức đích hỗ trợ sẽ bị bỏ qua hoặc sử dụng giá trị mặc định.
Một số khả năng đặc thù của giao thức (như tư duy mở rộng của Claude, bộ nhớ đệm prompt) có thể không được biểu đạt hoàn toàn sau khi chuyển đổi.
Quá trình chuyển đổi tạo ra độ trễ nhỏ (thường dưới 10ms).

Thực Hành Tốt Nhất: Ưu tiên sử dụng giao thức được mô hình đích hỗ trợ nguyên bản để có hỗ trợ tính năng đầy đủ nhất và hiệu suất tốt nhất.

Chuyển Đổi Định Dạng Tin Nhắn

OpenAI messages ↔ Claude messages

Sự Khác Biệt Xử Lý system prompt

OpenAI đặt system prompt làm tin nhắn đầu tiên trong mảng messages:

{
  "messages": [
    { "role": "system", "content": "Bạn là trợ lý kỹ thuật nghiêm ngặt." },
    { "role": "user", "content": "Giải thích cổng API là gì" }
  ]
}

Claude đặt system prompt trong trường độc lập cấp cao nhất:

{
  "system": "Bạn là trợ lý kỹ thuật nghiêm ngặt.",
  "messages": [
    { "role": "user", "content": "Giải thích cổng API là gì" }
  ]
}

Quy Tắc Chuyển Đổi:

OpenAI → Claude: Trích xuất tin nhắn role: "system" đầu tiên và di chuyển vào trường system.
Claude → OpenAI: Chuyển đổi nội dung trường system thành tin nhắn role: "system" và chèn vào đầu mảng messages.

Ánh Xạ vai trò

OpenAI	Claude	Gemini	Mô Tả
`system`	Trường cấp cao `system`	`systemInstruction`	Vị trí prompt hệ thống khác nhau
`user`	`user`	`user`	Tin nhắn người dùng, nhất quán
`assistant`	`assistant`	`model`	Phản hồi trợ lý/mô hình, tên khác nhau
`tool`	`tool_result` trong `user`	`functionResponse` trong `user`	Thuộc tính kết quả công cụ khác nhau

Cân Nhắc Chuyển Đổi:

Claude không chấp nhận hai tin nhắn liên tiếp cùng vai trò; chuyển đổi yêu cầu hợp nhất hoặc chèn tin nhắn giữ chỗ.
Vai trò model của Gemini được ánh xạ thành assistant khi chuyển đổi sang OpenAI.
role: "tool" của OpenAI được hợp nhất vào tin nhắn user trong cả Claude và Gemini.

OpenAI messages ↔ Gemini contents

Cấu trúc tin nhắn của Gemini được gọi là contents, vai trò của mỗi tin nhắn được gọi là role, và nội dung trong mảng parts:

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "Giải thích cổng API là gì" }]
    }
  ]
}

Quy Tắc Chuyển Đổi:

OpenAI messages ↔ Gemini contents
OpenAI content ↔ Gemini parts
OpenAI assistant ↔ Gemini model
system prompt chuyển đổi thành trường cấp cao systemInstruction

Bảng Ánh Xạ Tham Số

Tham Số Lấy Mẫu

OpenAI	Claude	Gemini	Mô Tả
`temperature`	`temperature`	`temperature`	Claude tối đa 1, OpenAI tối đa 2, Gemini tối đa 2
`top_p`	`top_p`	`topP`	nucleus sampling, cả ba đều hỗ trợ
Không hỗ trợ	`top_k`	`topK`	OpenAI không hỗ trợ, bỏ qua khi chuyển đổi
`max_tokens` / `max_completion_tokens`	`max_tokens` (bắt buộc)	`maxOutputTokens`	Claude yêu cầu thiết lập rõ ràng
`n`	Không hỗ trợ	`candidateCount`	Claude không hỗ trợ tạo nhiều ứng viên
`stop`	`stop_sequences`	`stopSequences`	Tên trường khác nhau, ngữ nghĩa nhất quán

Chuyển Đổi Phạm Vi Nhiệt Độ:

Khi temperature của yêu cầu OpenAI vượt quá 1 và đích là Claude, RouteAPI tự động cắt về 1 để tránh bị upstream từ chối.

Tham Số Kiểm Soát Đầu Ra

OpenAI	Claude	Gemini	Mô Tả
`response_format`	Không hỗ trợ	`responseMimeType`	OpenAI hỗ trợ chế độ JSON và JSON Schema
`frequency_penalty`	Không hỗ trợ	`frequencyPenalty`	Claude không hỗ trợ tham số phạt
`presence_penalty`	Không hỗ trợ	`presencePenalty`	Claude không hỗ trợ tham số phạt
`stream`	`stream`	`stream`	Cả ba đều hỗ trợ, nhưng định dạng sự kiện hoàn toàn khác nhau
`stream_options.include_usage`	Luôn trả về	Tự động trả về khi `generateContentRequest.stream=true`	Phương pháp trả về thống kê sử dụng khác nhau

Hành Vi Chuyển Đổi:

frequency_penalty và presence_penalty bị bỏ qua khi chuyển tiếp sang Claude.
response_format: { type: "json_object" } được mô phỏng thông qua gọi công cụ khi chuyển tiếp sang Claude, hoặc thêm prompt đầu ra JSON vào system.
n > 1 được đặt lại về 1 khi chuyển tiếp sang Claude, vì Claude không hỗ trợ tạo nhiều ứng viên.

Siêu Dữ Liệu và Kiểm Soát

OpenAI	Claude	Gemini	Mô Tả
`user`	`metadata.user_id`	Không hỗ trợ	Để phát hiện lạm dụng
`seed`	Không hỗ trợ	`seed`	Claude không hỗ trợ lấy mẫu xác định
`logprobs` / `top_logprobs`	Không hỗ trợ	Không hỗ trợ	Chỉ mô hình OpenAI hỗ trợ
Không hỗ trợ	`thinking`	Không hỗ trợ	Cấu hình tư duy mở rộng đặc thù của Claude

Chuyển Đổi Gọi Công Cụ

Sự Khác Biệt Định Dạng Định Nghĩa Công Cụ

Định dạng tools OpenAI

{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Truy vấn thời tiết hiện tại của thành phố được chỉ định",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "Tên thành phố" }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

Định dạng tools Claude

{
  "tools": [
    {
      "name": "get_weather",
      "description": "Truy vấn thời tiết hiện tại của thành phố được chỉ định",
      "input_schema": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "Tên thành phố" }
        },
        "required": ["city"]
      }
    }
  ]
}

Định dạng tools Gemini

{
  "tools": [
    {
      "functionDeclarations": [
        {
          "name": "get_weather",
          "description": "Truy vấn thời tiết hiện tại của thành phố được chỉ định",
          "parameters": {
            "type": "object",
            "properties": {
              "city": { "type": "string", "description": "Tên thành phố" }
            },
            "required": ["city"]
          }
        }
      ]
    }
  ]
}

Quy Tắc Chuyển Đổi Định Nghĩa Công Cụ

OpenAI	Claude	Gemini	Ghi Chú Chuyển Đổi
`tools[].type: "function"`	Không có cấp này	Không có cấp này	Xóa bao bọc `type` khi chuyển đổi
`tools[].function`	Làm phẳng trong `tools[]`	Đặt trong `functionDeclarations[]`	Cấu trúc phân cấp khác nhau
`function.parameters`	`input_schema`	`parameters`	Tên trường Claude khác nhau

Ánh Xạ tool_choice

OpenAI	Claude	Gemini	Mô Tả
`"auto"`	`{ "type": "auto" }`	`"AUTO"`	Mô hình quyết định tự động
`"none"`	`{ "type": "none" }`	`"NONE"`	Cấm gọi công cụ
`"required"`	`{ "type": "any" }`	`"ANY"`	Phải gọi công cụ
`{ "type": "function", "function": { "name": "get_weather" } }`	`{ "type": "tool", "name": "get_weather" }`	`{ "functionCallingConfig": { "allowedFunctionNames": ["get_weather"] } }`	Buộc gọi công cụ cụ thể, cấu trúc rất khác nhau

Chuyển Đổi Định Dạng Kết Quả Công Cụ

Kết Quả Công Cụ OpenAI

{
  "role": "tool",
  "tool_call_id": "call_abc123",
  "content": "Hà Nội, nắng, 23°C"
}

Kết Quả Công Cụ Claude

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Hà Nội, nắng, 23°C"
    }
  ]
}

Kết Quả Công Cụ Gemini

{
  "role": "user",
  "parts": [
    {
      "functionResponse": {
        "name": "get_weather",
        "response": { "result": "Hà Nội, nắng, 23°C" }
      }
    }
  ]
}

Điểm Chính Chuyển Đổi:

role: "tool" của OpenAI được hợp nhất vào tin nhắn user khi chuyển đổi sang Claude/Gemini.
Tên trường ID gọi công cụ khác nhau: tool_call_id vs tool_use_id vs nhận diện bằng tên hàm trong Gemini.
Claude và Gemini yêu cầu tất cả kết quả công cụ trong cùng một tin nhắn user; OpenAI cho phép nhiều tin nhắn tool riêng biệt.

Chuyển Đổi Nội Dung Đa Phương Thức

Chuyển Đổi Định Dạng URL Hình Ảnh

Định Dạng OpenAI

{
  "role": "user",
  "content": [
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/image.jpg",
        "detail": "high"
      }
    },
    { "type": "text", "text": "Mô tả hình ảnh này" }
  ]
}

Định Dạng Claude

{
  "role": "user",
  "content": [
    {
      "type": "image",
      "source": {
        "type": "url",
        "url": "https://example.com/image.jpg"
      }
    },
    { "type": "text", "text": "Mô tả hình ảnh này" }
  ]
}

Định Dạng Gemini

{
  "role": "user",
  "parts": [
    {
      "fileData": {
        "mimeType": "image/jpeg",
        "fileUri": "https://example.com/image.jpg"
      }
    },
    { "text": "Mô tả hình ảnh này" }
  ]
}

Xử Lý Mã Hóa Base64

Định dạng base64 OpenAI

{
  "type": "image_url",
  "image_url": {
    "url": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }
}

Định dạng base64 Claude

{
  "type": "image",
  "source": {
    "type": "base64",
    "media_type": "image/jpeg",
    "data": "/9j/4AAQSkZJRg..."
  }
}

Định dạng base64 Gemini

{
  "inlineData": {
    "mimeType": "image/jpeg",
    "data": "/9j/4AAQSkZJRg..."
  }
}

Quy Tắc Chuyển Đổi:

URI data: của OpenAI được phân tích, media_type được trích xuất từ tiền tố URI, phần base64 thuần túy được chuyển cho giao thức đích.
Claude yêu cầu trường media_type riêng biệt, không chấp nhận URI data:.
Gemini sử dụng inlineData thay vì fileData để biểu diễn nội dung base64.
Tham số detail của OpenAI (low/high) bị mất khi chuyển đổi; Claude và Gemini không có khái niệm tương đương.

Xử Lý Tham Số Không Được Hỗ Trợ

Tham Số Nào Không Thể Chuyển Đổi

Tham Số	Giao Thức Nguồn	Không Thể Chuyển Sang	Lý Do
`top_k`	Claude, Gemini	OpenAI	OpenAI không hỗ trợ lấy mẫu top-k
`n`	OpenAI, Gemini	Claude	Claude không hỗ trợ tạo nhiều ứng viên
`frequency_penalty` / `presence_penalty`	OpenAI, Gemini	Claude	Claude không có tham số phạt
`logprobs`	OpenAI	Claude, Gemini	Chỉ mô hình OpenAI trả về xác suất logarit
`thinking`	Claude	OpenAI, Gemini	Cấu hình tư duy mở rộng đặc thù của Claude
`cache_control`	Claude	OpenAI, Gemini	Kiểm soát bộ nhớ đệm prompt đặc thù của Claude
`reasoning_effort`	OpenAI	Claude, Gemini	Tham số đặc thù của dòng o1 OpenAI
`response_format` (JSON Schema)	OpenAI	Claude, Gemini	Ràng buộc JSON Schema đầy đủ chỉ OpenAI hỗ trợ

Cách Xử Lý Tham Số Không Tương Thích

RouteAPI sử dụng các chiến lược sau:

Bỏ Qua Im Lặng: Tham số không được hỗ trợ bị xóa khi chuyển đổi mà không ảnh hưởng đến sự thành công của yêu cầu (ví dụ: detail, logprobs).
Điều Chỉnh Tự Động: Giá trị ngoài phạm vi được cắt về phạm vi hợp lệ (ví dụ: temperature > 1 cắt về 1 khi chuyển tiếp sang Claude).
Hạ Cấp Bảo Thủ: Tính năng phức tạp được mô phỏng bằng phương pháp đơn giản (ví dụ: JSON Schema của OpenAI hạ cấp thành gọi công cụ hoặc ràng buộc prompt trên Claude).
Từ Chối Yêu Cầu: Hiếm khi, nếu tham số cốt lõi không thể chuyển đổi và không có giá trị mặc định hợp lý, trả về lỗi 400 (ví dụ: giao thức Claude thiếu max_tokens).

Cảnh Báo và Thông Báo Lỗi

RouteAPI cung cấp thông tin chuyển đổi trong tiêu đề phản hồi và nhật ký:

X-RouteAPI-Protocol-Conversion: openai-to-claude
X-RouteAPI-Dropped-Params: frequency_penalty,presence_penalty

Nếu chuyển đổi thất bại hoặc tham số xung đột, trả về phản hồi lỗi chuẩn:

{
  "error": {
    "message": "Parameter 'max_tokens' is required for Claude models",
    "type": "invalid_request_error",
    "param": "max_tokens",
    "code": "missing_required_parameter"
  }
}

Thực Hành Tốt Nhất

Sử Dụng Giao Thức Nguyên Bản: Sử dụng giao thức nguyên bản của mô hình càng nhiều càng tốt để tránh mất mát chuyển đổi.
Tránh Phụ Thuộc Tính Năng Đặc Thù Giao Thức: Đừng phụ thuộc vào khả năng đặc thù của một giao thức như logprobs, thinking trừ khi bạn chắc chắn chỉ sử dụng mô hình của giao thức đó.
Kiểm Tra Tiêu Đề Phản Hồi: Chú ý đến tiêu đề X-RouteAPI-Dropped-Params để biết tham số nào bị bỏ qua.
Kiểm Tra Tương Thích Xuyên Giao Thức: Xác thực hành vi của cùng một yêu cầu trong các kết hợp giao thức/mô hình khác nhau trong môi trường thử nghiệm.
Ghi Log ID Mô Hình: Ghi lại ID mô hình thực sự được gọi và loại giao thức trong nhật ký để dễ dàng khắc phục sự khác biệt.

Chuẩn Hóa Định Dạng Phản Hồi

Chuẩn Hóa Trường usage

Giao Thức	Trường token đầu vào	Trường token đầu ra	Trường tổng token
OpenAI	`prompt_tokens`	`completion_tokens`	`total_tokens`
Claude	`input_tokens`	`output_tokens`	Không có (tự tính)
Gemini	`promptTokenCount`	`candidatesTokenCount`	`totalTokenCount`

Quy Tắc Chuyển Đổi:

Claude → OpenAI: input_tokens → prompt_tokens, output_tokens → completion_tokens, tính total_tokens = input_tokens + output_tokens.
Gemini → OpenAI: promptTokenCount → prompt_tokens, candidatesTokenCount → completion_tokens, totalTokenCount → total_tokens.
OpenAI → Claude: prompt_tokens → input_tokens, completion_tokens → output_tokens, xóa total_tokens.

Các trường bộ nhớ đệm prompt của Claude cũng được giữ lại:

{
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 45,
    "total_tokens": 165,
    "cache_creation_input_tokens": 80,
    "cache_read_input_tokens": 40
  }
}

Chuẩn Hóa finish_reason

OpenAI	Claude	Gemini	Ý Nghĩa
`stop`	`end_turn`	`STOP`	Kết thúc tự nhiên
`length`	`max_tokens`	`MAX_TOKENS`	Đạt giới hạn độ dài
`tool_calls`	`tool_use`	`STOP` (với functionCall)	Yêu cầu gọi công cụ
`content_filter`	Không có tương đương	`SAFETY`	Bị chặn bởi bộ lọc nội dung
`stop`	`stop_sequence`	`STOP`	Đạt chuỗi dừng

Quy Tắc Chuyển Đổi:

Claude end_turn → OpenAI stop
Claude max_tokens → OpenAI length
Claude tool_use → OpenAI tool_calls
Gemini STOP được ánh xạ thành stop hoặc tool_calls dựa trên sự hiện diện của functionCall
Gemini SAFETY → OpenAI content_filter

Thống Nhất Phản Hồi Lỗi

Tất cả phản hồi lỗi của giao thức được chuyển đổi sang định dạng OpenAI (khi khách hàng sử dụng giao thức OpenAI):

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Lỗi gốc Claude:

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

Sau khi chuyển đổi sang định dạng OpenAI, type được ánh xạ thành invalid_request_error, code được đặt thành invalid_api_key.

Ví Dụ Chuyển Đổi

Ví Dụ 1: Yêu Cầu OpenAI → Định Dạng Claude

Yêu Cầu OpenAI Gốc:

{
  "model": "claude-sonnet-4-5",
  "messages": [
    {
      "role": "system",
      "content": "Bạn là trợ lý kỹ thuật nghiêm ngặt, giữ câu trả lời ngắn gọn."
    },
    {
      "role": "user",
      "content": "Giải thích cổng API là gì"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 150,
  "stream": false
}

Yêu Cầu Claude Đã Chuyển Đổi:

{
  "model": "claude-sonnet-4-5",
  "system": "Bạn là trợ lý kỹ thuật nghiêm ngặt, giữ câu trả lời ngắn gọn.",
  "messages": [
    {
      "role": "user",
      "content": "Giải thích cổng API là gì"
    }
  ],
  "temperature": 0.7,
  "max_tokens": 150,
  "stream": false
}

Thay Đổi Chính:

Tin nhắn system được trích xuất từ mảng messages vào trường cấp cao system.
messages giờ chỉ chứa tin nhắn user và assistant.

Ví Dụ 2: Gọi Công Cụ Claude → Định Dạng OpenAI

Phản Hồi Gọi Công Cụ Claude:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-5",
  "content": [
    {
      "type": "text",
      "text": "Để tôi kiểm tra thời tiết Hà Nội."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "city": "Hà Nội" }
    }
  ],
  "stop_reason": "tool_use",
  "usage": {
    "input_tokens": 120,
    "output_tokens": 45
  }
}

Chuyển Đổi Sang Định Dạng OpenAI:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "object": "chat.completion",
  "created": 1726567890,
  "model": "claude-sonnet-4-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Để tôi kiểm tra thời tiết Hà Nội.",
        "tool_calls": [
          {
            "id": "toolu_01A09q90qw90lq917835lq9",
            "type": "function",
            "function": {
              "name": "get_weather",
              "arguments": "{\"city\":\"Hà Nội\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 45,
    "total_tokens": 165
  }
}

Thay Đổi Chính:

Mảng content được chia: khối text được trích xuất thành trường content, khối tool_use được chuyển đổi thành mảng tool_calls.
Đối tượng tool_use.input được tuần tự hóa thành chuỗi JSON function.arguments.
stop_reason: "tool_use" → finish_reason: "tool_calls".
input_tokens → prompt_tokens, output_tokens → completion_tokens, thêm total_tokens.
Thêm các trường cấp cao định dạng OpenAI: object, created, mảng choices.

Ví Dụ 3: Đa Phương Thức Gemini → Định Dạng OpenAI

Phản Hồi Gemini:

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": "Hình ảnh này hiển thị giao diện người dùng hiện đại với thanh điều hướng, khu vực nội dung và thanh bên."
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 258,
    "candidatesTokenCount": 32,
    "totalTokenCount": 290
  }
}

Chuyển Đổi Sang Định Dạng OpenAI:

{
  "id": "chatcmpl-gemini-abc123",
  "object": "chat.completion",
  "created": 1726567890,
  "model": "gemini-2.0-flash-exp",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hình ảnh này hiển thị giao diện người dùng hiện đại với thanh điều hướng, khu vực nội dung và thanh bên."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 258,
    "completion_tokens": 32,
    "total_tokens": 290
  }
}

Thay Đổi Chính:

candidates[0].content.parts[0].text → choices[0].message.content.
role: "model" → role: "assistant".
finishReason: "STOP" → finish_reason: "stop" (chuyển sang chữ thường).
Tên trường usageMetadata được ánh xạ sang cấu trúc usage của OpenAI.

Tóm Tắt Thực Hành Tốt Nhất

1. Chọn Giao Thức Phù Hợp

Chọn giao thức dựa trên loại khách hàng và mô hình:

Loại Khách Hàng	Mô Hình Đích	Giao Thức Đề Xuất	Lý Do
SDK OpenAI	Mô hình OpenAI	OpenAI	Hỗ trợ nguyên bản, không chuyển đổi
Claude Code	Mô hình Claude	Claude Messages	Hỗ trợ nguyên bản, không chuyển đổi
LangChain / LiteLLM	Bất kỳ mô hình nào	OpenAI	Tương thích hệ sinh thái tốt nhất
SDK Anthropic	Mô hình Claude	Claude Messages	Truy cập tư duy mở rộng, bộ nhớ đệm prompt
Khách hàng tùy chỉnh	Bất kỳ mô hình nào	Tùy nhu cầu	Ưu tiên giao thức nguyên bản của mô hình đích

2. Tránh Tính Năng Đặc Thù Giao Thức

Nếu doanh nghiệp cần chuyển đổi mô hình, tránh sử dụng các tính năng này:

Đặc thù OpenAI: logprobs, seed, ràng buộc JSON Schema đầy đủ, reasoning_effort (dòng o1)
Đặc thù Claude: thinking, cache_control, mcp_servers
Đặc thù Gemini: grounding, codeExecution

Tập hợp tính năng phổ quát (cả ba đều hỗ trợ):

Hội thoại cơ bản (messages / contents)
Đầu ra luồng (stream)
Kiểm soát nhiệt độ (temperature, chú ý sự khác biệt phạm vi)
Gọi công cụ (tools, chú ý sự khác biệt định dạng)
Đầu vào đa phương thức (hình ảnh, chú ý sự khác biệt định dạng)
Chuỗi dừng (stop / stop_sequences / stopSequences)

3. Kiểm Tra Tương Thích Xuyên Giao Thức

Xác thực các kịch bản này trong môi trường thử nghiệm:

Cùng giao thức, mô hình khác nhau: Đảm bảo giao thức OpenAI gọi đúng mô hình Claude và Gemini.
Giao thức khác nhau, cùng mô hình: Xác minh tính nhất quán kết quả khi gọi cùng một mô hình Claude qua giao thức Claude Messages và OpenAI.
Vòng gọi công cụ: Kiểm tra định nghĩa công cụ, gọi và truyền kết quả có đúng qua các giao thức.
Tham số biên: Kiểm tra trường hợp biên như temperature: 1.5 (OpenAI hợp lệ, Claude cần cắt), n: 2 (OpenAI hỗ trợ, Claude không).
Xử lý lỗi: Xác minh lỗi upstream được chuyển đổi đúng sang định dạng giao thức khách hàng.

4. Giám Sát và Ghi Log

Ghi lại thông tin sau để khắc phục sự cố chuyển đổi giao thức:

{
  "request_id": "req_abc123",
  "client_protocol": "openai",
  "model_id": "claude-sonnet-4-5",
  "upstream_protocol": "claude",
  "conversion_required": true,
  "dropped_params": ["frequency_penalty", "logprobs"],
  "adjusted_params": {"temperature": {"original": 1.8, "adjusted": 1.0}},
  "latency_ms": 856,
  "conversion_overhead_ms": 8
}

Chỉ số chính:

Tỷ lệ thành công chuyển đổi: Phần trăm lỗi 400 do chuyển đổi giao thức thất bại.
Độ trễ chuyển đổi: Độ trễ bổ sung do chuyển đổi giao thức (thường 5-15ms).
Tỷ lệ bỏ tham số: Tham số nào thường bị bỏ qua, có ảnh hưởng đến doanh nghiệp không.
Tỷ lệ lỗi xuyên giao thức: Tỷ lệ lỗi gọi OpenAI → Claude có cao hơn OpenAI → OpenAI không.

5. Chiến Lược Di Chuyển Dần

Nếu di chuyển từ giao thức này sang giao thức khác:

Giai đoạn 1: Kiểm tra ghi kép: Kết quả gọi giao thức mới chỉ dùng để so sánh, không ảnh hưởng doanh nghiệp.
Giai đoạn 2: Chuyển đổi dần: Lưu lượng nhỏ chuyển sang giao thức mới, giám sát tỷ lệ lỗi và chất lượng phản hồi.
Giai đoạn 3: Chuyển đổi hoàn toàn: Chuyển toàn bộ lưu lượng sau khi xác nhận không có bất thường.
Giai đoạn 4: Dọn dẹp mã cũ: Xóa mã chuyển đổi giao thức cũ.

Mỗi giai đoạn cần xác thực:

Tính chính xác chức năng (gọi công cụ, đa phương thức, đầu ra luồng)
Chất lượng phản hồi (sự khác biệt đầu ra giữa các kết hợp giao thức/mô hình khác nhau)
Chỉ số hiệu suất (độ trễ, sử dụng token, chi phí)
Xử lý lỗi (bất thường mạng, giới hạn tốc độ, sự cố upstream)

Chuyển đổi giao thức cho phép bạn linh hoạt chọn khách hàng và mô hình, nhưng thực hành tốt nhất vẫn là ưu tiên sử dụng giao thức nguyên bản của mô hình đích. Nếu cần gọi xuyên giao thức, hãy xác thực kỹ lưỡng trong môi trường thử nghiệm và giám sát các lỗi và chỉ số hiệu suất liên quan đến chuyển đổi trong môi trường sản xuất.