API tương thích OpenAI của Ollama: Truy cập, Giá, Tích hợp và Hướng dẫn Production

API tương thích OpenAI của Ollama: Truy cập, Giá, Tích hợp và Hướng dẫn Production

API tương thích OpenAI của Ollama cho phép một ứng dụng giữ nguyên cấu trúc SDK OpenAI quen thuộc trong khi gửi yêu cầu đến máy chủ Ollama cục bộ hoặc trực tiếp tới Ollama Cloud. Điều này hữu ích, nhưng không đảm bảo tính tương đương tính năng một-một: Ollama ghi nhận hỗ trợ một tập con của API OpenAI, và một số khả năng phụ thuộc vào endpoint và mô hình bạn chọn.

Hướng dẫn này trình bày cách truy cập giao diện này, cấu hình nó trong một ứng dụng Python hoặc JavaScript hiện có, hiểu chi phí cloud so với cục bộ, và thiết lập các ranh giới production thực tế cho nó.

Trả lời nhanh: dùng http://localhost:11434/v1/ cho máy chủ Ollama cục bộ và một khóa API giữ chỗ được SDK yêu cầu nhưng Ollama bỏ qua. Dùng https://ollama.com/v1 cùng với OLLAMA_API_KEY để truy cập cloud trực tiếp. Xác thực endpoint và mô hình chính xác trước khi phụ thuộc vào hành vi streaming, vision, tools, structured output hoặc Responses API.

“Tương thích OpenAI” có nghĩa gì đối với Ollama?

Đây là một bề mặt tích hợp dành cho client OpenAI, không phải API do OpenAI lưu trữ. Nó cho phép bạn trỏ các client tương thích đến các base URL của Ollama và sử dụng các route được hỗ trợ như chat completions, embeddings, khám phá mô hình và các yêu cầu Responses không trạng thái.

Tài liệu tham chiếu tương thích của Ollama là nguồn xác thực cho tập con được hỗ trợ. Cụ thể:

• /v1/chat/completions hỗ trợ các tính năng bao gồm streaming, JSON mode, vision, tools, đầu ra có thể tái lập, logprobs và các điều khiển chỉ áp dụng cho những mô hình tương thích.
• /v1/embeddings hỗ trợ đầu vào dạng chuỗi và mảng.
• /v1/models và /v1/models/{model} hỗ trợ khám phá mô hình, nhưng một số trường được trả về có ý nghĩa riêng của Ollama.
• POST /v1/responses khả dụng, nhưng nó không trạng thái: không dựa vào previous_response_id hoặc conversation.

Xem tài liệu tham chiếu tương thích OpenAI của Ollama trực tiếp trước khi bật một khả năng trong production. “Tương thích” nên được xem là lý do để tái sử dụng client và cấu trúc yêu cầu của bạn—không phải lý do để bỏ qua kiểm thử tính năng.

Truy cập API tương thích OpenAI của Ollama: cục bộ so với cloud

Lựa chọn triển khai đơn giản nhất là liệu suy luận chạy trên máy của bạn hay truy cập endpoint cloud của Ollama.

Sự phân chia này được ghi lại trong phần giới thiệu API và hướng dẫn xác thực của Ollama. Các lệnh gọi cloud trực tiếp cần khóa API. Các lệnh gọi cục bộ thì không.

Thiết lập cục bộ

Cài đặt Ollama, sau đó pull mô hình bạn định sử dụng. Tài liệu của Ollama đưa ra mẫu tổng quát sau:

ollama pull gpt-oss:20b
ollama serve

Bây giờ hãy xác thực rằng endpoint cục bộ có thể liệt kê các mô hình:

curl http://localhost:11434/v1/models

Nếu kết nối đó thất bại, hãy giải quyết vấn đề máy chủ cục bộ trước khi thay đổi mã ứng dụng. Việc di chuyển client dễ gỡ lỗi hơn nhiều khi base URL API và danh mục mô hình đã hoạt động độc lập.

Thiết lập cloud trực tiếp

Để dùng cloud trực tiếp, hãy tạo khóa API trong tài khoản Ollama của bạn và đặt nó trong một biến môi trường:

export OLLAMA_API_KEY="replace-with-your-key"

Base URL cloud là https://ollama.com/v1. Ollama ghi nhận rằng API hosted của họ sử dụng Authorization: Bearer; không đặt khóa dài hạn trong mã trình duyệt, repository hoặc tệp cấu hình phía client.

Tích hợp API tương thích OpenAI của Ollama với SDK OpenAI

Điểm di chuyển là cấu hình client. Giữ các message ứng dụng và xử lý lỗi phía sau giao diện riêng của bạn, sau đó chỉ thay đổi base URL, khóa và cấu hình mô hình.

Python: máy chủ cục bộ

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1/",
    api_key="ollama",  # required by the SDK; ignored by the local server
)

response = client.chat.completions.create(
    model="gpt-oss:20b",
    messages=[
        {"role": "user", "content": "Summarize the production risks of exposing a local API."}
    ],
)

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

Điểm cuối cục bộ không xác thực yêu cầu. Khóa giữ chỗ chỉ tồn tại vì ứng dụng khách OpenAI yêu cầu một giá trị; nó không bảo vệ máy chủ cục bộ.

Python: đám mây trực tiếp

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://ollama.com/v1",
    api_key=os.environ["OLLAMA_API_KEY"],
)

response = client.chat.completions.create(
    model="gemma4:31b",
    messages=[
        {"role": "user", "content": "Give one sentence on safe API key storage."}
    ],
)

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

Cấu trúc mã được cố ý giữ tương tự. Điểm khác biệt về vận hành thì không: các lệnh gọi đám mây trực tiếp phụ thuộc vào khóa API và mô hình đám mây đã chọn; các lệnh gọi cục bộ phụ thuộc vào mô hình đã pull và tài nguyên sẵn có trên máy chủ.

JavaScript: giữ điểm cuối có thể cấu hình

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.OLLAMA_BASE_URL ?? "http://localhost:11434/v1/",
  apiKey: process.env.OLLAMA_API_KEY ?? "ollama",
});

const completion = await client.chat.completions.create({
  model: process.env.OLLAMA_MODEL ?? "gpt-oss:20b",
  messages: [{ role: "user", content: "Return a concise health-check message." }],
});

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

Thiết lập biến môi trường theo từng môi trường triển khai:

# Local
OLLAMA_BASE_URL=http://localhost:11434/v1/
OLLAMA_API_KEY=ollama
OLLAMA_MODEL=gpt-oss:20b

# Direct cloud
OLLAMA_BASE_URL=https://ollama.com/v1
OLLAMA_API_KEY=replace-with-your-key
OLLAMA_MODEL=gemma4:31b

Cấu hình này giúp việc thay đổi tuyến hoặc mô hình về sau trở nên rõ ràng và có thể xem xét. Nó cũng ngăn URL cơ sở dành riêng cho một môi trường trở thành hành vi ẩn của ứng dụng.

Ma trận tương thích: cần kiểm thử gì trước khi phát hành

API tương thích OpenAI của Ollama hữu ích nhất khi bạn biến tính tương thích thành một kế hoạch kiểm thử thay vì một giả định.

Hai chi tiết thường khiến các nhóm bất ngờ:

1. Trạng thái thuộc về ứng dụng của bạn. Ứng dụng của bạn nên lưu các message hoặc trạng thái hội thoại cần thiết thay vì kỳ vọng hành vi Responses có trạng thái từ Ollama.
2. Tên mô hình không phải là bảo đảm về năng lực. Một yêu cầu có thể dùng điểm cuối tương thích nhưng vẫn không cung cấp chất lượng hoặc hành vi tool mà quy trình làm việc cần. Hãy kiểm thử mô hình, kích thước prompt, giới hạn đầu ra và tools cùng nhau.

Nếu một tích hợp hiện có hard-code tên mô hình OpenAI mặc định, Ollama tài liệu hóa ollama cp như một cách để tạo bí danh mô hình cục bộ tạm thời. Chỉ sử dụng cách này như một shim tương thích có chủ đích, ghi lại bí danh và loại bỏ nó khi cấu hình của bạn đã rõ ràng.

Giá Ollama: TCO cục bộ so với mức giá token đám mây

Giá cho API tương thích OpenAI của Ollama phụ thuộc vào tuyến sử dụng.

Suy luận cục bộ không phải là hóa đơn theo token—nhưng không phải không có chi phí

Chạy mô hình cục bộ không tạo ra hóa đơn đám mây Ollama theo từng token. Tuy vậy, nó tạo ra một cấu hình chi phí vận hành:

• Năng lực GPU hoặc CPU, RAM/VRAM, lưu trữ và khấu hao máy móc
• Điện năng và làm mát
• Thời gian pull mô hình và lưu trữ image
• Lập kế hoạch năng lực, giám sát, vá lỗi và ứng phó sự cố
• Chi phí cơ hội của việc giữ mô hình ở trạng thái sẵn sàng cho các yêu cầu độ trễ thấp

Đối với một nhà phát triển đơn lẻ, đây có thể là một sự đánh đổi tuyệt vời. Đối với sản phẩm có lưu lượng truy cập tăng đột biến hoặc nhiều mô hình, hãy tính toán mức sử dụng phần cứng và công sức đảm bảo độ tin cậy cùng với chi phí suy luận thô.

Giá đám mây trực tiếp được công bố theo mỗi triệu token

Trang giá trực tiếp của Ollama liệt kê mức giá đám mây trên mỗi một triệu token, bao gồm các mức giá riêng cho đầu vào, đầu vào đã lưu đệm và đầu ra. Các ví dụ bên dưới được kiểm tra vào ngày 22 tháng 10 năm 2026; hãy sử dụng bảng giá trực tiếp để đưa ra quyết định mua sắm và triển khai.

Trang giá của Ollama cũng mô tả mức giá ngoài giờ cao điểm cho các mục đủ điều kiện. Đừng lập ngân sách chỉ dựa trên nhãn mô hình: hãy sử dụng dòng giá áp dụng cho tuyến, mô hình và thời điểm thực tế.

Một ước tính hàng tháng thực tế là:

monthly_cloud_cost =
  (input_tokens / 1,000,000 × input_rate)
+ (cached_input_tokens / 1,000,000 × cached_input_rate)
+ (output_tokens / 1,000,000 × output_rate)

Ví dụ: theo mức giá gpt-oss:20b được công bố ở trên, 1 triệu token đầu vào không lưu đệm cộng với 250.000 token đầu ra ước tính là $0.145 trước bất kỳ thay đổi giá hoặc khoản tín dụng dành riêng cho tài khoản nào. Hãy sử dụng dữ liệu đo từ xa về token quan sát được, thay vì độ dài cuộc trò chuyện phỏng đoán, để dự báo cho môi trường production.

Hướng dẫn production: bảo mật máy chủ cục bộ trước khi đưa ra bên ngoài

Quy tắc production quan trọng nhất đối với API tương thích OpenAI của Ollama rất đơn giản: máy chủ Ollama cục bộ mặc định không yêu cầu xác thực.

Ollama mặc định liên kết với 127.0.0.1:11434. Tài liệu của Ollama cho thấy OLLAMA_HOST có thể thay đổi địa chỉ liên kết và một proxy như Nginx có thể chuyển tiếp lưu lượng đến máy chủ. Đây là các tùy chọn triển khai—không phải xác thực. Nếu bạn đưa dịch vụ ra ngoài localhost, hãy đặt các biện pháp kiểm soát có chủ đích xung quanh dịch vụ đó.

Danh sách kiểm tra production

1. Giữ liên kết loopback mặc định trừ khi bạn có đường truy cập được xác định. Không đưa trực tiếp cổng 11434 ra internet.
2. Đặt TLS và xác thực ở biên. Sử dụng reverse proxy, mạng riêng, danh tính dịch vụ và ủy quyền theo từng client phù hợp với môi trường của bạn. Khóa OpenAI SDK giả không phải là biện pháp kiểm soát truy cập.
3. Chỉ cho phép hẹp các origin của trình duyệt. Ollama ghi nhận OLLAMA_ORIGINS cho các origin được cho phép bổ sung. Chỉ thêm chính xác các origin của ứng dụng web hoặc tiện ích mở rộng cần truy cập; không biến nó thành cách bỏ qua cross-origin bao quát.
4. Sử dụng danh sách cho phép mô hình. Hãy coi model được yêu cầu là đầu vào cần xác thực. Các bên gọi trong production không nên có thể tải mô hình tùy ý hoặc chọn các mô hình chưa được xem xét.
5. Thiết lập chính sách hàng đợi và xử lý quá tải. Ollama ghi nhận rằng máy chủ quá tải có thể trả về HTTP 503 và cung cấp OLLAMA_MAX_QUEUE. Sử dụng số lần thử lại có giới hạn với exponential backoff và jitter, sau đó trả về lỗi được kiểm soát cho bên gọi.
6. Lập kế hoạch dung lượng VRAM và tính đồng thời cùng nhau. OLLAMA_NUM_PARALLEL tăng mức song song trên mỗi mô hình, nhưng yêu cầu bộ nhớ cũng tăng theo. OLLAMA_MAX_LOADED_MODELS và OLLAMA_KEEP_ALIVE xác định mức độ tích cực mà các mô hình chiếm dụng bộ nhớ.
7. Giám sát các đường dẫn quan trọng. Theo dõi độ trễ, thời gian xếp hàng, HTTP 503, danh mục mô hình đang hoạt động, kích thước yêu cầu, ngắt kết nối luồng, lỗi gọi công cụ và áp lực bộ nhớ GPU/CPU. ollama ps giúp xác minh vị trí các mô hình đã tải đang chạy.
8. Kiểm thử khởi động lại và khởi động nguội. Một mô hình cục bộ có thể cần thời gian tải sau khi triển khai hoặc bị loại khỏi bộ nhớ. Hãy thực hiện các bài diễn tập tải, rollback và timeout trước khi API hỗ trợ một quy trình hướng đến khách hàng.
9. Không để bí mật trong client. Đối với chế độ đám mây, hãy lưu OLLAMA_API_KEY trong trình quản lý bí mật phía máy chủ hoặc môi trường runtime được bảo vệ—không phải trong frontend bundle.
10. Ghim bộ kiểm thử chấp nhận, không chỉ phiên bản dependency. Chạy lại các kiểm thử chat, streaming, công cụ, JSON, vision và trạng thái phản hồi bất cứ khi nào bạn nâng cấp Ollama, thay đổi mô hình hoặc điều chỉnh lớp định tuyến.

FAQ của Ollama ghi lại địa chỉ liên kết, cấu hình CORS, hành vi hàng đợi, cài đặt đồng thời và các biện pháp kiểm soát cục bộ/đám mây đằng sau các khuyến nghị này.

Lộ trình triển khai an toàn hơn

Hãy sử dụng trình tự này cho một ứng dụng bắt đầu cục bộ và có thể sử dụng các mô hình được lưu trữ sau này:

1. Xác minh endpoint cục bộ. Tải một mô hình, liệt kê các mô hình và gửi một chat completion không streaming.
2. Ổn định cấu hình client OpenAI. Biến URL cơ sở, khóa API và mô hình thành các biến môi trường—không phải các giá trị literal rải rác khắp codebase.
3. Tạo bộ kiểm thử tương thích. Bao gồm đầu ra JSON, streaming, mọi schema công cụ, đầu vào vision khi phù hợp, hành vi timeout và các yêu cầu không hợp lệ.
4. Kiểm thử tải máy chủ. Ghi lại độ trễ, độ sâu hàng đợi, VRAM/RAM và thời điểm bắt đầu xuất hiện lỗi 503.
5. Thêm một lớp biên có xác thực trước khi truy cập từ xa. Giữ Ollama ở chế độ riêng tư phía sau dịch vụ ứng dụng hoặc proxy đáng tin cậy.
6. Đánh giá chế độ đám mây riêng biệt. Sử dụng khóa đám mây chuyên dụng, các mô hình trong danh sách cho phép, cảnh báo ngân sách và các trường hợp kiểm thử bao quát những giới hạn Responses dành riêng cho đám mây.
7. Tách rời lựa chọn nhà cung cấp khỏi logic nghiệp vụ. Nếu sản phẩm cần so sánh các mô hình được lưu trữ hoặc thêm tuyến dự phòng, hãy giữ hợp đồng OpenAI client phía sau một adapter nhỏ.

Đối với bước cuối cùng, checklist chuyển đổi API gateway tương thích OpenAI có thể giúp bạn tách biệt việc tích hợp client khỏi lựa chọn nhà cung cấp mô hình. Nếu bạn muốn đánh giá nhiều nhà cung cấp được lưu trữ mà không cần thêm một mẫu client mới cho từng nhà cung cấp, hãy xem hướng dẫn nhanh Flatkey API và hướng dẫn xác định khi nào AI API gateway hữu ích.

Các lỗi thường gặp với API tương thích OpenAI của Ollama

Coi máy chủ localhost như một dịch vụ được bảo mật

Một yêu cầu cục bộ có thể hoạt động vì tiến trình nằm trên cùng một máy, chứ không phải vì quyền truy cập đã được xác thực. Ngay khi địa chỉ bind, tunnel, proxy hoặc cổng container thay đổi, hãy xem xét lại danh tính, chính sách mạng, TLS và ghi nhật ký kiểm toán.

Giả định tính tương đương tính năng với OpenAI

Ollama chỉ hỗ trợ rõ ràng một tập con của OpenAI API. Hãy tích hợp kiểm tra năng lực vào CI và kiểm thử ngữ nghĩa—không chỉ phản hồi 200. Một định nghĩa công cụ có thể được phân tích cục bộ nhưng hoạt động khác sau khi thay đổi mô hình.

Dùng nhãn giá đám mây làm ngân sách

Mức giá đầu vào, đầu vào được cache và đầu ra có thể khác nhau đáng kể. Hãy ghi log các trường token, tính chi phí hiệu dụng cho mỗi tác vụ thành công và kiểm tra lại trang giá trước khi cam kết một ngân sách cố định.

Tăng mức song song mà không có mô hình bộ nhớ

Nhiều yêu cầu song song hơn có thể làm tăng yêu cầu về context và bộ nhớ. Hãy theo dõi áp lực thực tế trên máy chủ với các prompt đại diện trước khi thay đổi cài đặt đồng thời.

Cấp khóa đám mây cho trình duyệt

Lệnh gọi trực tiếp từ trình duyệt đến đám mây khiến việc xoay vòng khóa, kiểm soát ngân sách và ngăn chặn lạm dụng trở nên khó khăn hơn nhiều. Hãy giữ khóa đám mây ở backend đáng tin cậy và chỉ cung cấp thao tác mà ứng dụng của bạn cần.

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

API tương thích OpenAI của Ollama có giống OpenAI API không?

Không. Lớp tương thích của Ollama hỗ trợ một tập con đã được tài liệu hóa của OpenAI API để các client tương thích có thể kết nối với Ollama. Hãy xác nhận từng endpoint và trường trong tài liệu tham chiếu về khả năng tương thích của Ollama trước khi coi một tính năng là có thể di chuyển giữa các nền tảng.

Ollama API cục bộ có cần khóa API không?

Không. Ollama cho biết API cục bộ không yêu cầu xác thực. Giá trị api_key="ollama" trong các ví dụ SDK là yêu cầu client phải không rỗng, không phải thông tin xác thực. Hãy giữ máy chủ cục bộ trên localhost hoặc thêm các biện pháp kiểm soát thực sự trước khi công khai truy cập từ xa.

Ollama Cloud có cần khóa API không?

Có. Truy cập trực tiếp trên đám mây tới https://ollama.com/v1 yêu cầu một khóa API được truyền dưới dạng Bearer token. Hãy lưu trữ khóa ở phía máy chủ.

Tôi có thể sử dụng /v1/responses không?

Có, đối với các yêu cầu Responses không có trạng thái. Đừng phụ thuộc vào previous_response_id hoặc conversation. Tài liệu đám mây cũng nêu rõ các giới hạn liên quan đến tìm kiếm web tích hợp và việc phát lại lệnh gọi công cụ tùy chỉnh/freeform.

API tương thích OpenAI của Ollama có miễn phí không?

Suy luận cục bộ không có phí Ollama Cloud theo token, nhưng bạn vẫn phải trả chi phí cho phần cứng và vận hành mà bạn sử dụng. Suy luận trực tiếp trên đám mây áp dụng mức giá theo token được công bố và tín dụng tài khoản.

Khi nào tôi nên dùng gateway thay thế?

Hãy dùng trực tiếp Ollama khi tuyến cục bộ/đám mây đáp ứng nhu cầu về mô hình, quyền riêng tư và vận hành của workload. Hãy cân nhắc gateway khi sản phẩm của bạn cần tích hợp nhất quán giữa nhiều nhà cung cấp được lưu trữ, quy trình đánh giá mô hình hoặc một tuyến dự phòng riêng. Hãy bắt đầu bằng một quyết định rõ ràng về unified AI API, sau đó duy trì cùng một client adapter ở cấp ứng dụng.

Kết luận

API tương thích OpenAI của Ollama mang đến cho nhà phát triển một cách thực tế để tái sử dụng OpenAI SDK với các mô hình chạy cục bộ hoặc được phục vụ qua đám mây. Việc triển khai an toàn không chỉ là thay đổi URL cơ sở: đó là một ma trận năng lực đã được kiểm thử, mô hình chi phí cục bộ so với đám mây rõ ràng, ranh giới triển khai cục bộ riêng tư và kế hoạch đã được kiểm thử tải cho hàng đợi cùng bộ nhớ mô hình.

Hãy bắt đầu với local nếu bạn cần quyền kiểm soát và có thể vận hành phần cứng. Hãy dùng cloud trực tiếp khi bạn muốn suy luận được lưu trữ thông qua cùng một kiểu client. Trong cả hai trường hợp, hãy giữ lựa chọn endpoint có thể cấu hình và đảm bảo mỗi tính năng được hỗ trợ đều xứng đáng có mặt trong bộ kiểm thử production của bạn.