Hướng dẫn API tương thích OpenAI — từ endpoint cục bộ của Ollama đến các mô hình frontier lưu trữ

"Tương thích với OpenAI" có nghĩa là API sử dụng cùng định dạng truyền tải như /v1/chat/completions của OpenAI — vì vậy mọi SDK hoặc công cụ OpenAI đều hoạt động với nó chỉ bằng cách thay đổi base_url. Ollama cung cấp một endpoint tương thích với OpenAI cho các mô hình chạy cục bộ trên máy của bạn. Kunavo cung cấp một endpoint cho các mô hình frontier được lưu trữ — Claude, GPT cùng các mô hình hình ảnh, video và âm thanh — phía sau một bearer token. Hướng dẫn này trình bày mẫu đó và cách chuyển đổi giữa chúng mà không cần viết lại mã.

“Tương thích với OpenAI” nghĩa là gì

Định dạng OpenAI Chat Completions đã trở thành tiêu chuẩn trên thực tế: một mảng messages ở đầu vào, một choices[].message ở đầu ra, Server-Sent Events cho streaming và tools cho việc gọi hàm. Mọi endpoint tuân thủ hợp đồng đó đều là “tương thích với OpenAI”, và các SDK openai chính thức (Python, Node cùng mọi bản port cộng đồng) trỏ đến nó bằng cách thiết lập base_url.

Mẫu Ollama (cục bộ)

Ollama chạy các mô hình mở cục bộ và cung cấp chúng tại http://localhost:11434/v1:

from openai import OpenAI

# Ollama exposes an OpenAI-compatible endpoint on localhost
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

resp = client.chat.completions.create(
    model="llama3.1",
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Cùng mã, các mô hình frontier được lưu trữ (Kunavo)

Trỏ chính SDK đó đến Kunavo và chọn một mô hình frontier. Chỉ base_url, api_key và model thay đổi — lệnh gọi giống hệt từng byte:

import os
from openai import OpenAI

# Same SDK, same call shape — only base_url, api_key and model change
client = OpenAI(
    base_url="https://api.kunavo.com/v1",
    api_key=os.environ["KUNAVO_API_KEY"],
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # or claude-haiku-4-5, gpt-5-5, gpt-5-6-terra...
    messages=[{"role": "user", "content": "Summarize this changelog."}],
)
print(resp.choices[0].message.content)

Lấy khóa tại /app/keys; hướng dẫn bắt đầu nhanh có các dạng Node và curl.

Cục bộ và được lưu trữ — khi nào dùng cái nào

Một thiết lập phổ biến: Ollama trên localhost để phát triển ngoại tuyến, Kunavo để có chất lượng được lưu trữ trong production — một biến môi trường sẽ chuyển đổi giữa chúng. Để xem hợp đồng theo từng trường mà cả hai đầu triển khai — tham số, các delta streaming, tool_calls, đối tượng usage và bảng đối chiếu với bề mặt v1 của Ollama — hãy xem tài liệu tham khảo /v1/chat/completions và phần tương thích OpenAI của Ollama.

Khám phá mô hình lúc chạy

Tương tự /api/tags của Ollama, Kunavo cung cấp một danh mục có cấu trúc OpenAI. Hãy phân giải slug lúc chạy thay vì hardcode:

# Discover every enabled model (OpenAI-shaped, like Ollama's /api/tags)
curl https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer $KUNAVO_API_KEY"

Ngoài chat

Cùng một khóa có thể truy cập các endpoint hình ảnh (/v1/images/generations), video (/v1/video/generations) và âm thanh — tất cả đều có cấu trúc OpenAI. Xem hướng dẫn AI đa phương thức và so sánh OpenRouter để biết Kunavo khác các gateway khác như thế nào.

Một bề mặt vượt xa định nghĩa thông thường của “tương thích” và đáng lưu ý: POST /v1/responses. Codex CLI chỉ chấp nhận nhà cung cấp tùy chỉnh qua Responses API, đó là lý do hầu hết gateway tương thích với OpenAI hoàn toàn không thể điều khiển nó — Codex tính phí theo token như thế nào giải quyết vấn đề này bằng một khối cấu hình có thể chạy. Để định giá một khối lượng công việc GPT bao gồm đầu vào được lưu trong bộ nhớ đệm, công cụ tính giá API OpenAI sử dụng số token của chính bạn.

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