Ollama API: thay OpenAI trong code, n8n và Dify

Trả lời nhanh: Ollama phục vụ hai bộ API ở cổng 11434: API riêng (/api/generate, /api/chat) và endpoint tương thích OpenAI (/v1/chat/completions). Nghĩa là hầu hết code, thư viện, công cụ đang gọi OpenAI chỉ cần đổi base URL thành http://dia-chi-may:11434/v1 (api key điền chuỗi bất kỳ) là chạy bằng model local, n8n, Dify, LangChain đều theo công thức đó.

Sức mạnh thật của Ollama không nằm ở cửa sổ chat mà ở API: mọi thứ bạn từng xây quanh OpenAI, script, workflow n8n, app Dify, chuỗi LangChain, đều cắm được vào model local gần như không sửa code. Bài này đi qua từng nền tảng phổ biến với cấu hình cụ thể, phần streaming và embeddings, cùng các bẫy khiến người ta tưởng API hỏng trong khi chỉ là thiếu một dòng.

Gọi thử trong 60 giây: curl và Python

# chuan OpenAI-compatible:
curl http://localhost:11434/v1/chat/completions -d '{
  "model": "qwen2.5:7b",
  "messages": [{"role": "user", "content": "Xin chào!"}]
}'

# Python - thu vien openai chinh chu, chi doi 2 dong:
from openai import OpenAI
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
r = client.chat.completions.create(model="qwen2.5:7b",
    messages=[{"role": "user", "content": "Tóm tắt giúp tôi..."}])
print(r.choices[0].message.content)

api_key bắt buộc có mặt nhưng giá trị tùy ý, Ollama không kiểm. Streaming hoạt động y chuẩn OpenAI (stream=True), app chat hiển thị chữ chạy như thường.

n8n: workflow AI không tốn token

Trong n8n, các node AI (AI Agent, Basic LLM Chain, OpenAI Chat Model) đều nhận custom base URL: tạo credential OpenAI mới, Base URL điền http://dia-chi-ollama:11434/v1, api key điền bừa, model điền qwen2.5:14b. Từ đó mọi workflow, phân loại email, tóm tắt đơn hàng, bot trả lời, chạy model local: không hóa đơn token, dữ liệu khách không rời hạ tầng. n8n và Ollama chung một VPS thì địa chỉ là localhost; n8n chạy Docker thì trỏ http://host.docker.internal:11434 (hoặc IP host), bẫy quen của mọi setup container.

Dify và LangChain: khai một lần, dùng cả app

Dify (đã có bài self-host trên VPS): Settings → Model Provider → thêm Ollama, Base URL http://dia-chi:11434 (provider Ollama của Dify dùng API gốc, không cần /v1), khai tên model và context size, xong là mọi app trong Dify chọn được model local như chọn GPT. LangChain: dùng thẳng lớp ChatOllama/OllamaEmbeddings trong gói langchain-ollama, hoặc đi đường OpenAI-compatible như mọi framework khác. Nguyên tắc chung cho mọi công cụ chưa kể tên: cứ tìm ô Base URL, có ô đó là cắm được Ollama.

Embeddings: mảnh RAG hay bị quên

RAG cần hai model: sinh văn bản và embeddings (biến câu chữ thành vector để tìm kiếm ngữ nghĩa). Ollama phục vụ luôn phần hai:

ollama pull nomic-embed-text
curl http://localhost:11434/api/embeddings -d '{
  "model": "nomic-embed-text", "prompt": "đoạn văn cần mã hóa"}'

Kết hợp pgvector hay Qdrant là đủ bộ RAG chạy hoàn toàn trong nhà, không một byte tài liệu nào ra ngoài. Kiến trúc đầy đủ nằm ở bài RAG offline của series.

Ba bẫy khiến API tưởng như hỏng

1. Gọi từ máy khác bị từ chối, Ollama mặc định chỉ nghe 127.0.0.1: phải đặt OLLAMA_HOST=0.0.0.0 (qua systemd override), nhưng khoan, đừng mở xong để trần cổng 11434 cho cả internet: cách mở an toàn qua tailnet là chủ đề bài kế tiếp. 2. Lượt gọi đầu timeout, model đang nạp từ đĩa vào RAM; tăng timeout phía client lên 120s và chỉnh keep_alive để không tái diễn. 3. Trả lời bị cắt cụt với tài liệu dài, num_ctx mặc định nhỏ, ngữ cảnh tràn bị cắt âm thầm: nâng num_ctx trong Modelfile hoặc tham số API.

Bảng đối chiếu địa chỉ theo cách triển khai

Bẫy lớn nhất khi cắm Ollama vào công cụ khác là điền sai địa chỉ. Bảng này giải quyết gần hết các ca:

Riêng Dify dùng giao diện gốc của Ollama nên điền địa chỉ không kèm /v1. Các công cụ theo chuẩn tương thích OpenAI thì phải có /v1. Đây là khác biệt nhỏ khiến nhiều người mất cả buổi.

Mở cho máy khác gọi, đúng cách

sudo systemctl edit ollama

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_KEEP_ALIVE=30m"
Environment="OLLAMA_MAX_LOADED_MODELS=2"
Environment="OLLAMA_NUM_PARALLEL=2"

sudo systemctl daemon-reload && sudo systemctl restart ollama
curl http://127.0.0.1:11434/api/tags     # liet ke model dang co
ss -tlnp | grep 11434                     # xac nhan dang nghe tren 0.0.0.0

Ý nghĩa các biến: OLLAMA_KEEP_ALIVE giữ model trong bộ nhớ sau lần gọi cuối, đặt 30 phút thì lần gọi sau không phải nạp lại từ ổ đĩa, đây là cách chữa dứt điểm lỗi lần gọi đầu quá lâu. OLLAMA_MAX_LOADED_MODELS giới hạn số model giữ cùng lúc, đặt cao mà RAM ít là máy tráo trang liên tục. OLLAMA_NUM_PARALLEL là số yêu cầu xử lý song song cho mỗi model.

Cảnh báo bảo mật: đặt OLLAMA_HOST=0.0.0.0 là mở cổng cho mọi nơi chạm tới được máy. Ollama không có xác thực. Phơi cổng 11434 ra internet nghĩa là ai cũng dùng được máy chủ của bạn, và trong một số phiên bản còn đọc và xóa được model. Chỉ mở trong mạng nội bộ hoặc qua mạng riêng ảo, kèm tường lửa:

sudo ufw allow from 192.168.1.0/24 to any port 11434
sudo ufw deny 11434

Ước lượng RAM và VRAM cần cho từng cỡ model

Cộng thêm phần bộ nhớ cho ngữ cảnh: cửa sổ ngữ cảnh càng dài càng tốn, và đây là chỗ hay bị thiếu khi xử lý tài liệu dài. Xem model đang chiếm bao nhiêu và đang ở đâu bằng ollama ps, cột Processor cho biết đang chạy trên CPU hay GPU.

Ba bẫy còn lại khi ghép vào quy trình tự động

• Lần gọi đầu sau khi máy chủ rảnh lâu bị quá thời gian chờ. Model phải nạp lại từ ổ đĩa. Đặt OLLAMA_KEEP_ALIVE dài, tăng thời gian chờ phía công cụ gọi lên 120 giây, và với quy trình chạy theo lịch thì gọi một câu ngắn để làm nóng trước khi chạy việc thật.
• Kết quả trả về không đúng định dạng JSON mà quy trình cần. Dùng tham số format: json của Ollama, hoặc khai lược đồ dữ liệu mong muốn. Model nhỏ hay thêm lời dẫn trước và sau khối JSON, và đó là nguyên nhân số một khiến bước tiếp theo trong quy trình đứng.
• Chạy nhiều yêu cầu song song thì chậm hẳn. Model dùng chung một bộ nhớ, tăng OLLAMA_NUM_PARALLEL mà không đủ RAM sẽ phản tác dụng. Với quy trình xử lý hàng loạt, xếp hàng tuần tự thường nhanh hơn ép song song.

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

Code đang dùng SDK OpenAI có phải cài thêm gì không?

Không, chính SDK openai (Python/JS) dùng được luôn, chỉ đổi base_url và api_key. Đó là chủ đích của endpoint tương thích: giữ nguyên code, đổi nơi chạy.

Ollama API có xác thực không? Có an toàn không?

Không có lớp xác thực tích hợp, ai gọi được cổng 11434 là dùng được. Vì vậy tuyệt đối không phơi cổng này ra internet công cộng; chạy sau tailnet hoặc reverse proxy có auth. Series có bài riêng về việc này.

Một API phục vụ được bao nhiêu người dùng đồng thời?

Ollama xếp hàng và xử song song có giới hạn (điều chỉnh bằng OLLAMA_NUM_PARALLEL); thông lượng thật phụ thuộc CPU/GPU và cỡ model. Đội nhỏ dùng chatbot nội bộ: model 7-14B trên VPS nhiều nhân là êm; hàng chục người gọi dồn dập thì cần GPU hoặc chia nhiều máy.

Dùng được function calling / tools qua API không?

Được với các model hỗ trợ tools (Qwen 2.5, Llama 3.1 trở lên), qua cả API gốc lẫn endpoint OpenAI-compatible. Agent framework như LangChain, n8n AI Agent tận dụng được luôn.

Bài viết liên quan

• Self-host Dify.ai trên VPS: AI app platform thay LangFlow
• Chọn model Ollama tiếng Việt 2026: Qwen, Gemma hay Llama?
• Mở Ollama ra ngoài an toàn: đừng phơi port 11434