Dùng Gemini với OpenAI SDK qua endpoint tương thích
Gọi model Gemini từ OpenAI Python hoặc TypeScript SDK bằng cách trỏ base_url tới endpoint tương thích OpenAI của Google hoặc một gateway.
Bạn có thể gọi Gemini từ OpenAI SDK chính thức bằng cách đặt base_url tới endpoint tương thích OpenAI của Google (hoặc AI gateway đứng trước Gemini), xác thực bằng Gemini API key hoặc khóa gateway, và chọn model ID Gemini trong request chat.completions bình thường. Google ghi đường này trong hướng dẫn tương thích OpenAI Gemini. Team đã chuẩn hóa client OpenAI có thể đánh giá Gemini mà không viết lại mọi tích hợp.
Google cũng lưu ý rằng nếu bạn chưa dùng thư viện OpenAI, gọi Gemini API trực tiếp là lựa chọn mặc định được khuyến nghị để có đầy đủ tính năng. Tương thích là cầu nối cho migration và đánh giá, không phải tuyên bố rằng mọi bề mặt OpenAI đều tồn tại trên Gemini.
Vì sao tương thích OpenAI tăng tốc thử nghiệm Gemini
Nhiều codebase đã phụ thuộc gói openai, LangChain/OpenAI chat models, hoặc client tự viết cho /v1/chat/completions. Ép mỗi thí nghiệm sang native Gemini SDK nhân số helper auth, parser streaming và error handling. Tương thích cho phép:
- giữ một request builder và response parser;
- A/B Gemini trên traffic dạng OpenAI;
- chuyển credential ra sau gateway trong khi client vẫn đơn giản;
- tái sử dụng cùng tool schema agent trong giai giá sớm.
Tương thích vẫn là lớp dịch. Google mô tả hỗ trợ thư viện OpenAI đang tiếp tục mở rộng và một số bề mặt còn ở beta. Hãy đọc phần giới hạn hiện tại trước khi cam kết tương đương tính năng trong buổi review thiết kế.
Cấu hình client tối thiểu
Endpoint tương thích OpenAI Google trực tiếp
from openai import OpenAI
import os
client = OpenAI(
api_key=os.environ["GEMINI_API_KEY"],
base_url="https://generativelanguage.googleapis.com/v1beta/openai/",
)
response = client.chat.completions.create(
model="gemini-3.5-flash",
messages=[
{"role": "system", "content": "Answer with concrete engineering guidance."},
{
"role": "user",
"content": "When should a team try Gemini through an OpenAI client?",
},
],
)
print(response.choices[0].message.content)
TypeScript:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.GEMINI_API_KEY,
baseURL: "https://generativelanguage.googleapis.com/v1beta/openai/",
});
const response = await client.chat.completions.create({
model: "gemini-3.5-flash",
messages: [
{ role: "system", content: "Answer with concrete engineering guidance." },
{
role: "user",
content: "When should a team try Gemini through an OpenAI client?",
},
],
});
console.log(response.choices[0]?.message?.content);
Model ID thay đổi theo thời gian. Hãy ưu tiên danh sách model của Google hơn việc hardcode chuỗi snapshot Flash hoặc Pro cũ trong cấu hình production.
Đường gateway cho sản phẩm đa nhà cung cấp
client = OpenAI(
api_key="GATEWAY_API_KEY",
base_url="https://your-gateway.example.com/v1",
)
response = client.chat.completions.create(
model="gemini-flash", # stable alias mapped to gemini-3.5-flash (or successor)
messages=[{"role": "user", "content": "Draft a checklist for model A/B tests."}],
)
Đăng ký thông tin xác thực Gemini thượng nguồn một lần thành kênh, công bố alias trong model catalog và giới hạn secret ứng dụng ở khóa gateway. Đây là cùng mô hình vận hành được mô tả cho gateway API tương thích OpenAI.
Alias ổn định và ID thượng nguồn thô
Cấu hình ứng dụng nên phụ thuộc vào alias do operator kiểm soát:
- Công bố tên như
gemini-flashvàgemini-pro, hoặc nhãn riêng của sản phẩm. - Ánh xạ alias tới ID thượng nguồn hiện tại (
gemini-3.5-flash, một ID lớp Pro, v.v.). - Chỉ đổi ánh xạ khi Google phát hành model thay thế.
- Chạy bộ regression ngắn sau mỗi lần đổi ánh xạ.
Cách này giảm PR phía client và biến rollback thành chỉnh cấu hình. Kết hợp kỷ luật alias với định tuyến model theo độ trễ và chi phí để vị trí Flash và Pro luôn là quyết định sản phẩm rõ ràng.
Tính năng team thường thử trước
Chat thường và multi-turn
Bắt đầu bằng chat không streaming và bộ đánh giá cố định. Xác nhận:
- system instruction được tuân thủ
- ngữ cảnh nhiều lượt được giữ
- cắt bớt với
max_tokensphù hợp kỳ vọng sản phẩm - UI xử lý được từ chối và phản hồi rỗng
Streaming
Khi bật streaming cho Gemini:
- đo time-to-first-token tách biệt tổng thời gian
- quyết định UI hiển thị gì nếu luồng kết thúc bằng error chunk
- tránh failover âm thầm sau khi token đã được render
Quy tắc cho lỗi đầu luồng và giữa luồng thuộc chiến lược failover LLM API, không phải retry tùy tiện ở client.
Tools và function calling
tools = [
{
"type": "function",
"function": {
"name": "search_docs",
"description": "Search internal engineering docs",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"limit": {"type": "integer"},
},
"required": ["query"],
},
},
}
]
response = client.chat.completions.create(
model="gemini-3.5-flash",
messages=[{"role": "user", "content": "Find runbooks for gateway failover."}],
tools=tools,
tool_choice="auto",
)
Kiểm tra tên tool theo allowlist và kiểm tra đối số bằng JSON Schema hoặc Pydantic trước mọi side effect. Chi tiết khả chuyển và ma trận không tương thích nằm trong gọi tool khả chuyển giữa các nhà cung cấp.
Ánh xạ mức suy luận / thinking
Model Gemini có thể phơi bày cấu hình suy luận qua các trường tương thích OpenAI. Mỗi model Gemini ánh xạ reasoning effort khác nhau; hãy xem bảng ánh xạ hiện tại của Google khi tinh chỉnh mức model “suy nghĩ”. Gateway cũng có thể chấp nhận hậu tố effort trên alias cho client chỉ đặt được model string. Hãy coi đó là tiện ích của operator và ghi rõ alias nào ánh xạ tới effort nào.
Embeddings và endpoint lân cận
Embeddings và workflow media thường cần kiểm tra endpoint riêng. Trang tương thích OpenAI của Google ưu tiên mẫu chat; upload/download file cho một số luồng batch vẫn có thể cần client Google gốc. Hãy xác minh từng bề mặt lân cận bằng curl riêng trước khi tuyên bố “toàn bộ OpenAI SDK hoạt động”.
Hạn chế và lệch cần dự trù
- tham số OpenAI không được hỗ trợ hoặc bị bỏ qua âm thầm
- khác biệt mã hóa phần đa phương thức, nhất là ảnh và âm thanh
- trường hợp biên của tool calling: gọi song song, object đối số rỗng, enum lệch
- safety filter trả dạng từ chối khác OpenAI
- khoảng trống beta Google vẫn liệt kê trong giới hạn hiện tại
- khác biệt header rate limit và lỗi
Khi request trả 400 trên Gemini nhưng thành công trên OpenAI, hãy bỏ từng trường chỉ có ở OpenAI và ghi body lỗi thô. Đừng “sửa” bằng cách bắt mọi exception rồi retry nhà cung cấp khác giữa luồng.
Kế hoạch đánh giá tránh tự tin giả
- Đóng băng bộ 20–50 prompt, kèm tên tool call mong đợi khi phù hợp.
- Chạy bộ đó trên model mặc định hiện tại và
gemini-3.5-flash, hoặc alias Pro của bạn. - Chấm tính hợp lệ schema và tool bắt buộc tách biệt chất lượng văn xuôi.
- Đo p50/p95 latency và chi phí mỗi tác vụ thành công.
- Chỉ sau đó mới đổi policy định tuyến. Nếu Gemini thắng về latency nhưng thua về schema, chỉ định tuyến workflow chấp nhận văn bản tự do hơn.
Kiểm curl
curl https://your-gateway.example.com/v1/chat/completions \
-H "Authorization: Bearer $GATEWAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gemini-flash",
"messages": [
{"role": "user", "content": "Reply with the single word ready."}
]
}'
Test Google trực tiếp thì đổi host sang https://generativelanguage.googleapis.com/v1beta/openai/ và dùng Gemini API key. Môi trường chia sẻ nên ưu tiên đường gateway.
Vận hành Gemini như một channel
Trong đội đa nhà cung cấp, Gemini nên trông như mọi kênh khác:
- thông tin xác thực lưu phía máy chủ
- alias model được review khi Google đổi tên hoặc loại bỏ ID
- rate limit và budget có phạm vi theo team hoặc sản phẩm
- health và tỷ lệ lỗi hiển thị cạnh nhà cung cấp khác
- bối cảnh giá được review khi đổi định tuyến mặc định
Đó là cách gateway LLM đa nhà cung cấp duy trì khả năng vận hành: Gemini là đích định tuyến, không phải kiến trúc ứng dụng thứ hai.
An ninh và vệ sinh khóa
- Không nhúng khóa Gemini trong trình duyệt hoặc ứng dụng di động.
- Ưu tiên khóa gateway có phạm vi và quyền tối thiểu cho từng dịch vụ.
- Ghi log đối số tool cẩn thận; agent có thể đưa dữ liệu nhạy cảm của người dùng vào function call.
- Xem hướng dẫn OWASP LLM khi agent tự động gọi tool bên ngoài; quyền tự chủ quá mức là rủi ro sản phẩm, không chỉ rủi ro model.
Chuỗi migration
- Bật Gemini channel và verify
/v1/chat/completionsbằng curl. - Trỏ một service không critical tới Gemini alias.
- Chạy evaluation suite và so schema/tool success rates.
- Thêm streaming client.
- Thêm agent tool với server-side argument validation.
- Quyết định pinned, canary hay failover.
- Ghi rollback alias trước khi mở traffic.
Tài liệu tham chiếu
- Tương thích OpenAI của Gemini API
- Các model Gemini API
- Tài liệu Chat Completions của OpenAI
- Hướng dẫn function calling của OpenAI
Kiểm tra lần cuối: 2026-07-15. Xác nhận model ID, đường dẫn endpoint và bảng giới hạn trong tài liệu Google trước khi khóa định tuyến production.
FAQ
Endpoint tương thích OpenAI của Gemini có phải clone OpenAI đầy đủ?
Không. Đây là lớp tương thích cho workflow client OpenAI phổ biến. Một số endpoint, tham số và hành vi khác. Hãy đọc phần giới hạn của Google cho tính năng bạn phụ thuộc. Google vẫn khuyến nghị Gemini API gốc nếu bạn chưa đầu tư vào thư viện OpenAI.
Dùng Gemini qua base URL Google hay qua gateway?
Base URL Google cho thí nghiệm local nhanh. Gateway khi có nhiều service, team, nhà cung cấp, budget hoặc audit.
Nên bắt đầu model Gemini nào?
Bắt đầu bằng ID lớp Flash hiện tại trong tài liệu Google — tại thời điểm viết, mẫu dùng gemini-3.5-flash — cho đánh giá nhạy latency, và model lớp Pro cho reasoning hoặc tool workflow khó hơn. Ánh xạ chúng tới alias gateway ổn định thay vì rải ID thô trong cấu hình ứng dụng.
Giữ nguyên tool schema như OpenAI được không?
Thường được cho port ban đầu, nhưng validate từng schema. Parallel tool calling, strict JSON và encoding argument biên cần test tường minh trên Gemini.
Canary Gemini đầu tiên
Tạo hoặc chọn một kênh Gemini, gọi /v1/chat/completions bằng OpenAI SDK qua gateway và chạy bộ đánh giá cố định 20 prompt có ít nhất một tool call. So sánh tỷ lệ thành công schema và latency với model mặc định hiện tại, rồi quyết định Gemini là mặc định, canary hay failover cho workflow đó.