Claude OpenAI SDK Anthropic Chat Completions API tương thích

Dùng Claude với OpenAI SDK mà không phải viết lại client

Gọi Claude bằng OpenAI SDK để đánh giá, rồi dùng gateway chuyển đầu vào kiểu OpenAI sang Claude Messages gốc trong production.

AveMujica API 15 thg 7, 2026 10 phút đọc

Bạn có thể trỏ OpenAI SDK chính thức cho Python hoặc TypeScript tới Claude bằng cách đổi base_url, khóa API và model ID, rồi tiếp tục dùng chat.completions. Anthropic mô tả cách này trong hướng dẫn tương thích OpenAI SDK. Cùng một dạng client cũng có thể gọi gateway API tương thích OpenAI, nơi giữ thông tin xác thực Anthropic ở phía máy chủ và chuyển yêu cầu kiểu OpenAI thành Claude Messages gốc ở thượng nguồn.

Hai con đường này không tương đương. Tương thích trực tiếp dành cho đánh giá. Gateway production nói OpenAI với client và Claude Messages với Anthropic là một câu chuyện độ tin cậy khác.

Con đường đánh giá và con đường production

Anthropic nói rõ lớp tương thích OpenAI của họ chủ yếu dành cho thử nghiệm và so sánh mô hình, đồng thời không phải giải pháp dài hạn hoặc sẵn sàng cho production trong phần lớn trường hợp. Hãy coi câu này là chính sách sản phẩm, không phải chú thích tiếp thị.

Con đường	Client	Thượng nguồn	Phù hợp nhất
Tương thích Anthropic trực tiếp	OpenAI SDK → `https://api.anthropic.com/v1/`	Bề mặt kiểu OpenAI của Anthropic	Đánh giá cục bộ, thử prompt, thử nghiệm ngắn
Đầu vào OpenAI qua gateway	OpenAI SDK → gateway `/v1` của bạn	Gateway chuyển sang Claude Messages gốc	Khóa dùng chung có phạm vi, quota, failover, sản phẩm đa nhà cung cấp
Anthropic SDK / Messages API gốc	Anthropic client	Toàn bộ tính năng Claude	Prompt caching, trích dẫn, chi tiết extended thinking, đầu ra có cấu trúc được bảo đảm

Dùng hàng đầu tiên để trả lời “Claude có đủ tốt trên bộ kiểm thử cố định của chúng ta không?”. Dùng hàng thứ hai khi nhiều dịch vụ cần Claude nhưng không nên tự giữ khóa Anthropic. Dùng hàng thứ ba khi bạn cần điều khiển gốc của Claude mà lớp tương thích bỏ qua hoặc không cung cấp.

Kênh Claude của repository này chuyển OpenAI Chat Completions thành Claude Messages (RequestOpenAI2ClaudeMessage và các adaptor liên quan). Đây không phải là chuyển tiếp nguyên trạng endpoint tương thích của Anthropic. Client vẫn gửi JSON kiểu OpenAI; control plane sở hữu việc ánh xạ, thông tin xác thực và nhật ký sử dụng.

Các giới hạn quan trọng của lớp tương thích OpenAI của Anthropic

Khi gọi api.anthropic.com bằng OpenAI SDK, tài liệu Anthropic hiện tại nêu rõ các khoảng trống sau. Hãy tính đến chúng trước khi ai đó tuyên bố “thay thế trực tiếp”.

strict trên tool bị bỏ qua. JSON đối số tool không được bảo đảm khớp schema. Hãy kiểm tra đối số trong runtime hoặc dùng đầu ra có cấu trúc gốc của Claude khi cần bảo đảm phía máy chủ.
Đầu vào âm thanh bị loại bỏ. Phần âm thanh đa phương thức bị bỏ qua thay vì bị từ chối bằng lỗi rõ ràng.
Prompt caching không được hỗ trợ trên con đường tương thích. Caching vẫn có qua SDK và API gốc của Anthropic.
Message system và developer được đưa lên đầu rồi nối lại thành một system message mở đầu. Anthropic chỉ hỗ trợ một system message ban đầu; các lượt system/developer giữa cuộc hội thoại kiểu OpenAI được ghép bằng ký tự xuống dòng.
Phần lớn trường không hỗ trợ bị bỏ qua âm thầm. Môi trường staging nên đóng an toàn nếu một trường làm thay đổi hành vi sản phẩm nhưng biến mất ở thượng nguồn.
Body lỗi giữ envelope kiểu OpenAI, nhưng nội dung chi tiết không tương đương OpenAI. Hãy ghi log để gỡ lỗi; đừng phân tích văn xuôi như một contract ổn định.

Các tính năng Claude đầy đủ như xử lý PDF, trích dẫn, extended thinking với quyền truy cập chi tiết hơn và prompt caching thuộc về API Claude gốc hoặc con đường gateway ánh xạ sang các trường gốc đó. Với vòng lặp tool của agent cần khả chuyển giữa nhiều thương hiệu, xem gọi tool khả chuyển giữa các nhà cung cấp.

Base URL Anthropic trực tiếp để đánh giá

Mẫu Python do Anthropic công bố:

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://api.anthropic.com/v1/",
)

response = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-opus-4-8; verify on Anthropic model docs
    messages=[
        {"role": "system", "content": "You are a precise API integration assistant."},
        {"role": "user", "content": "Summarize three risks of hardcoding provider SDKs."},
    ],
    max_tokens=800,
)

print(response.choices[0].message.content)

TypeScript:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ANTHROPIC_API_KEY,
  baseURL: "https://api.anthropic.com/v1/",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5",
  messages: [
    { role: "system", content: "You are a precise API integration assistant." },
    { role: "user", content: "Summarize three risks of hardcoding provider SDKs." },
  ],
  max_tokens: 800,
});

console.log(response.choices[0]?.message?.content);

Ví dụ chính thức thường dùng claude-opus-4-8. Tài liệu model Anthropic hiện tại cũng liệt kê Claude Sonnet 5 và Claude Haiku 4.5. Hãy ưu tiên bảng model đang hoạt động hơn mọi ảnh chụp trong bài viết, kể cả bài này.

Base URL gateway cho nhiều dịch vụ trong production

Khi Claude là một kênh trong số nhiều kênh, hãy trỏ cùng SDK tới gateway và chỉ giữ thông tin xác thực Anthropic ở máy chủ:

client = OpenAI(
    api_key="GATEWAY_API_KEY",
    base_url="https://your-gateway.example.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet",  # stable gateway alias mapped to a current Claude ID
    messages=[
        {
            "role": "user",
            "content": "Draft a migration checklist for SDK consolidation.",
        }
    ],
    max_tokens=800,
)

Operator ánh xạ alias như claude-sonnet hoặc claude-opus sang ID thượng nguồn thô (claude-sonnet-5, claude-opus-4-8, hoặc snapshot có ngày khi cần). Cấu hình ứng dụng nên phụ thuộc alias để việc đổi tên thượng nguồn chỉ là chỉnh kênh, không phải sự cố nhiều repository. Đó là control plane được mô tả trong gateway LLM đa nhà cung cấp.

Những phần thường chuyển nguyên trên con đường chung

Message

Lịch sử chat system / user / assistant thông thường hoạt động cho đánh giá và phần lớn chat sản phẩm.
Lượt system hoặc developer giữa cuộc hội thoại không được giữ thành role OpenAI riêng trên lớp tương thích Anthropic; hãy dự kiến hành vi ghép.
Viết policy rõ ràng. Đừng giả định Claude kế thừa chỉ dẫn ẩn chỉ được tinh chỉnh cho model OpenAI.

Tool

Định nghĩa tools kiểu OpenAI thường hoạt động trong giai đoạn đầu chuyển agent. Ví dụ:

tools = [
    {
        "type": "function",
        "function": {
            "name": "lookup_order",
            "description": "Fetch an order by ID from the shop system",
            "parameters": {
                "type": "object",
                "properties": {"order_id": {"type": "string"}},
                "required": ["order_id"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Where is order A-100?"}],
    tools=tools,
    tool_choice="auto",
)

message = response.choices[0].message
if message.tool_calls:
    for call in message.tool_calls:
        print(call.function.name, call.function.arguments)

Vì strict bị bỏ qua trên bề mặt tương thích Anthropic, hãy phân tích và kiểm tra arguments theo schema trước mọi side effect. Trên con đường gateway, vẫn phải kiểm tra trong tool executor; đừng bao giờ tin JSON do model phát ra.

Truyền luồng

Truyền luồng SSE phù hợp với phần lớn giao diện chat OpenAI hiện có. Hãy xác nhận độ trễ token đầu tiên, cách xử lý lỗi giữa luồng và việc gateway có chuẩn hóa sự kiện luồng Claude thành dạng client ổn định hay không. Tự động đổi nhà cung cấp sau khi đã phát một phần token khó hơn failover trước khi bắt đầu luồng; hãy kết hợp với chiến lược failover LLM API.

Khoảng trống về đầu ra có cấu trúc, an toàn và khả năng quan sát

Nếu pipeline phụ thuộc vào JSON Schema strict, hãy thử chính xác schema đó trên Claude trước khi tuyên bố tương đương. Khi strict mode chưa đầy đủ, hãy kiểm tra trong code ứng dụng hoặc dùng đầu ra có cấu trúc gốc của Claude.

Nhà cung cấp khác nhau về từ chối, header rate limit và hạch toán token ngay cả khi các khóa JSON trông giống nhau. Nếu client cần một contract chung, hãy chuẩn hóa lớp lỗi tại gateway. Đừng retry lỗi xác thực hoặc policy vĩnh viễn như lỗi 5xx tạm thời.

Khóa Anthropic trực tiếp và khóa gateway tạo ra dấu vết kiểm toán khác nhau. Team thường muốn lịch sử sử dụng nằm cạnh sức khỏe kênh thay vì chỉ trong console của một nhà cung cấp. Trang giá và danh mục model công khai hữu ích cho stakeholder; đừng rải URL operator cần xác thực trong mọi đoạn văn.

Trình tự chuyển đổi có kiểm soát

Kiểm kê các dịch vụ đã phụ thuộc OpenAI SDK hoặc /v1/chat/completions thô.
Chạy bộ đánh giá cố định với một Claude model ID trên endpoint tương thích Anthropic.
Đăng ký thông tin xác thực Anthropic thành một kênh gateway và công bố alias ổn định.
Trỏ một job nội bộ rủi ro thấp tới alias gateway; đừng chuyển chat khách hàng đầu tiên.
So sánh tính hợp lệ schema, tỷ lệ từ chối, độ trễ và chi phí mỗi tác vụ thành công.
Chỉ thêm tool và streaming sau khi chat thường đã ổn định.
Ghi rõ rollback: giữ alias model cũ hoạt động.

Kiểm tra nhanh qua HTTP

curl https://your-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet",
    "messages": [
      {"role": "user", "content": "Reply with the single word ready."}
    ],
    "max_tokens": 32
  }'

Hãy kỳ vọng JSON dạng Chat Completions với choices[0].message.content. Nếu envelope khác, sửa ánh xạ trước khi viết code sản phẩm.

Checklist production cho con đường gateway

Đánh giá đã chứng minh chất lượng trên bộ cố định; traffic production không dựa vào lớp tương thích Anthropic như chặng dài hạn.
Alias model ánh xạ tới Claude ID hiện tại trong tài liệu Anthropic hoặc catalog được duy trì.
Secret nằm trong gateway hoặc secret manager, không bao giờ trong trình duyệt hay ứng dụng di động.
max_tokens được đặt rõ; mặc định âm thầm có thể cắt câu trả lời dài.
Đối số tool được kiểm tra schema phía máy chủ; không phụ thuộc vào strict bị bỏ qua.
Client streaming xử lý kết quả cuối không đầy đủ và lỗi giữa luồng.
Dashboard chi phí và lỗi tách Claude khỏi nhà cung cấp khác.
Policy failover nêu rõ Claude là primary, backup hay bị ghim.

Khi gateway tốt hơn base URL Anthropic trực tiếp

Tín hiệu	Gateway giúp thế nào
Nhiều nhà cung cấp trong một sản phẩm	Một cấu hình client, nhiều kênh
Thông tin xác thực dùng chung toàn team	Khóa gateway có phạm vi thay vì chia sẻ khóa Anthropic
Rà soát chi tiêu	Lịch sử sử dụng thống nhất và bối cảnh giá
Mục tiêu độ tin cậy	Retry và failover mà không viết lại từng dịch vụ
Đội agent	Policy tập trung cho tool và định tuyến model

AveMujica API được xây dựng như control plane đó: đầu vào tương thích OpenAI, kênh nhà cung cấp, danh mục model và lịch sử vận hành. Nó không loại bỏ nhu cầu đọc ghi chú tương thích của Anthropic; nó ngăn các ghi chú đó biến thành năm nhánh client khác nhau.

Nguồn chính thức

Kiểm tra lần cuối: 2026-07-15. Hãy xác minh lại model ID và giới hạn tương thích trong tài liệu Anthropic trước khi đóng băng production.

Câu hỏi thường gặp

Con đường OpenAI SDK của Anthropic đã sẵn sàng cho production chưa?

Anthropic mô tả nó chủ yếu dành cho thử nghiệm và so sánh, không phải giải pháp production dài hạn cho phần lớn trường hợp. Với đội dịch vụ production, hãy ưu tiên gateway chuyển đầu vào OpenAI sang Claude Messages gốc, hoặc dùng API gốc của Anthropic khi cần tính năng chỉ có ở Claude.

Mọi trường Chat Completions của OpenAI có thể chạy nguyên trên Claude không?

Không. strict bị bỏ qua, âm thanh bị loại, prompt caching không có trên lớp tương thích, và các lượt system/developer bị ghép. Hãy thử chính xác dạng request bạn sẽ phát hành.

Nên đặt model string nào trong cấu hình ứng dụng?

Ưu tiên alias gateway (claude-sonnet) do operator ánh xạ tới ID hiện tại như claude-sonnet-5 hoặc claude-opus-4-8. Tránh hardcode snapshot cũ trong mọi dịch vụ.

Tôi vẫn cần Anthropic SDK chứ?

Có, khi bạn chủ ý cần điều khiển chỉ có ở API gốc, như dấu prompt caching, quyền truy cập đầy đủ vào extended thinking hoặc đầu ra có cấu trúc gốc. Giữ OpenAI SDK khi bề mặt kiểu OpenAI đã đủ và gateway sở hữu sự đa dạng nhà cung cấp.

Phát hành lần chuyển Claude đầu tiên

Chọn một dịch vụ đã dùng OpenAI SDK. Chứng minh chất lượng trên endpoint tương thích Anthropic, rồi chuyển dịch vụ đó sang alias gateway định tuyến tới Claude Messages. Chỉ sau khi chat thường đạt trạng thái xanh mới mở rộng tool và streaming, đồng thời so sánh traffic ngày đầu với baseline OpenAI trước đó.