API tương thích với OpenAI của Ollama

Ollama chạy các mô hình mã nguồn mở trên máy của bạn và cung cấp chúng qua một API tương thích với OpenAI tại http://localhost:11434/v1. Vì định dạng giao tiếp trùng khớp với OpenAI, OpenAI SDK chính thức có thể hoạt động với Ollama mà không cần chỉnh sửa — và cũng chính đoạn mã đó có thể truy cập các mô hình tiên tiến được lưu trữ bằng cách chỉ thay đổi URL cơ sở.

API tương thích với OpenAI của Ollama là gì

Ollama là một dự án mã nguồn mở riêng biệt để chạy cục bộ các mô hình như Llama, Qwen và Mistral. Bên cạnh API gốc, dự án cung cấp giao diện tương thích với OpenAI, giúp các công cụ được xây dựng cho OpenAI hoạt động mà không cần viết lại. API triển khai các endpoint mà hầu hết ứng dụng sử dụng:

API hỗ trợ chat, completions và embeddings (cùng đầu vào hình ảnh trên các mô hình cục bộ đa phương thức). API không tạo hình ảnh, video hoặc âm thanh. Kunavo triển khai cùng giao thức /v1/chat/completions — tài liệu tham khảo đó mô tả mọi tham số, cấu trúc delta khi truyền trực tuyến và đối tượng usage, đồng thời có bảng đối chiếu từng dòng với giao diện v1 của Ollama.

Gọi Ollama bằng OpenAI SDK

Trỏ base_url đến http://localhost:11434/v1. SDK yêu cầu api_key, nhưng Ollama cục bộ bỏ qua giá trị này — hãy truyền vào chuỗi bất kỳ. Đặt model thành mô hình bạn đã tải xuống (ví dụ: ollama pull llama3.2).

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",  # Ollama's OpenAI-compatible API
    api_key="ollama",  # required by the SDK, ignored by local Ollama
)

resp = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)

Hoặc dùng curl:

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "messages": [{"role": "user", "content": "Hello, Ollama"}]
  }'

Dùng cùng đoạn mã với các mô hình tiên tiến được lưu trữ

Ollama phù hợp cho phát triển ngoại tuyến và các công việc nhạy cảm về quyền riêng tư, nhưng các mô hình cục bộ chưa bằng những mô hình tiên tiến nhất về suy luận khó, lập trình và ngữ cảnh dài. Vì Kunavo cũng tương thích với OpenAI, bạn chỉ cần thay đổi hai dòng để chuyển lệnh gọi sang mô hình được lưu trữ — base_url và slug mô hình:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.kunavo.com/v1",  # only this line changes
    api_key="sk-kn-...",               # a real key now
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",  # a hosted frontier model
    messages=[{"role": "user", "content": "Explain quicksort in one paragraph."}],
)
print(resp.choices[0].message.content)

Chuyển đổi bằng biến môi trường

Một cách phổ biến là dùng Ollama cho phát triển cục bộ và mô hình được lưu trữ trong môi trường sản xuất, lựa chọn bằng biến môi trường. Mã ứng dụng và mã yêu cầu giống hệt nhau — chỉ base_url và mô hình là khác:

import os
from openai import OpenAI

# One client, switched by environment. Local for dev, hosted for prod.
if os.getenv("APP_ENV") == "production":
    client = OpenAI(base_url="https://api.kunavo.com/v1",
                    api_key=os.environ["KUNAVO_API_KEY"])
    MODEL = "claude-haiku-4-5"
else:
    client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
    MODEL = "llama3.2"

resp = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "ping"}],
)
print(resp.choices[0].message.content)

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

Tiếp theo nên xem gì

• Hướng dẫn API tương thích với OpenAI — từ endpoint cục bộ của Ollama đến các mô hình được lưu trữ
• AI gateway là gì? — mô hình một endpoint
• Tài liệu tham chiếu Chat Completions
• Bắt đầu nhanh — gửi request đầu tiên trong 60 giây