~/ / Bài viết về AI / LLM cục bộ trên VPS / Gọi mô hình cục bộ từ mã của bạn: structured outputs và API tương thích OpenAI trong Ollama

Gọi mô hình cục bộ từ mã của bạn: structured outputs và API tương thích OpenAI trong Ollama

Khi Ollama đã chạy trên máy chủ của bạn, mã của bạn cần hai thứ: một cách để nhận câu trả lời theo cấu trúc cố định, và một cách để truy cập máy chủ từ các thư viện vốn đã dùng API OpenAI. Ollama có tài liệu cho cả hai. Bài viết này tóm tắt trang structured outputs và trang tương thích OpenAI, đồng thời chỉ ra những gì tài liệu nói là không được hỗ trợ.

Đăng: 2026-10-26 · 5 phút đọc · Đã đối chiếu với tài liệu chính thức của Ollama vào 2026-10-26. Các tính năng được hỗ trợ thay đổi theo từng phiên bản, nên hãy xác nhận lại trong tài liệu hiện hành.

Hai cách gọi cùng một máy chủ

Ollama có API riêng, trong đó các ví dụ của tài liệu gửi POST tới http://localhost:11434/api/chat. Ollama cũng cung cấp API tương thích OpenAI dưới /v1/, để các client OpenAI hiện có có thể giao tiếp với nó chỉ bằng cách đổi base URL.

Mục	Native API	OpenAI-compatible API
Địa chỉ gốc	http://localhost:11434/api/chat	http://localhost:11434/v1/
Khóa API	không được nhắc đến trong các ví dụ	api_key='ollama', mà trang tài liệu ghi là bắt buộc nhưng bị bỏ qua
Trường cho structured output	format	response_format

Dòng về khóa API lấy từ ví dụ máy chủ cục bộ trong tài liệu. Với đám mây, trang tài liệu cho thấy base_url https://ollama.com/v1 cùng khóa API từ tài khoản Ollama của bạn, đó là một trường hợp khác.

Structured outputs: trường format

Trường format ràng buộc phản hồi. Nó nhận chuỗi json cho JSON thông thường, hoặc một đối tượng JSON schema. Trong các ví dụ cURL của tài liệu, phần thân yêu cầu có bốn trường: model, messages, stream đặt là false, và format. Schema trong các ví dụ có type, properties và required.

Giá trị của format	Tác dụng theo tài liệu
"json"	Mô hình trả lời bằng JSON thông thường
một đối tượng JSON schema	Phản hồi bị ràng buộc theo schema đó

Tài liệu nói rằng lý tưởng là truyền thêm JSON schema dưới dạng chuỗi trong prompt, để làm cơ sở cho phản hồi của mô hình.
Tài liệu cũng nói nên hạ temperature, ví dụ về 0, để kết quả hoàn thành mang tính xác định hơn.
Với Python và JavaScript, tài liệu gợi ý định nghĩa schema bằng Pydantic hoặc Zod, để có thể dùng lại cho việc xác thực.
Các mô hình thị giác chấp nhận cùng tham số format. Ví dụ về thị giác trong tài liệu truyền một hình ảnh cùng với một schema.
Theo trang tài liệu, đám mây của Ollama hiện chưa hỗ trợ structured outputs.

Trước khi dựa vào một schema, hãy kiểm tra nó. JSON Schema Validator bên dưới cho bạn biết bản thân schema có hợp lệ không và một câu trả lời mẫu có khớp với nó không.

Kiểm tra schema bạn gửi đi

Một schema có lỗi có thể thất bại muộn, khi yêu cầu đầu tiên đến được mô hình. Hãy dán schema và một mẫu JSON bạn mong đợi, rồi xem chúng có khớp nhau không.

Dùng thử: JSON Schema Validator

JSON SchemaDữ liệu JSON

Theo JSON Schema Draft 2020-12 đối với các từ khóa được hỗ trợ. Chỉ đọc $ref bên trong cùng một schema.

Mọi thứ chạy trong trình duyệt của bạn. Schema và dữ liệu không được tải lên.

Các endpoint tương thích OpenAI

Endpoint	Những gì trang tài liệu liệt kê	Được liệt kê là không hỗ trợ
/v1/chat/completions	chat, streaming, JSON mode, đầu ra có thể tái lập, thị giác, tools, điều khiển suy luận	logprobs, tool_choice, logit_bias, user, n; URL hình ảnh (hãy dùng base64)
/v1/completions	completions, streaming, JSON mode, đầu ra có thể tái lập	logprobs, best_of, echo, logit_bias, user, n
/v1/models	liệt kê và truy xuất mô hình	không được liệt kê
/v1/embeddings	đầu vào là chuỗi hoặc mảng chuỗi, định dạng mã hóa, số chiều	mảng token, user
/v1/responses	streaming, tools gọi hàm, tóm tắt suy luận	yêu cầu có trạng thái: previous_response_id, conversation, truncation

Trên endpoint chat, trang tài liệu liệt kê các trường yêu cầu sau trong số những trường được hỗ trợ: response_format, tools, stream, stream_options, seed, stop, temperature, top_p, max_tokens, frequency_penalty và presence_penalty.
Trang tài liệu nêu rằng structured outputs hoạt động qua API tương thích OpenAI thông qua response_format.
Nếu mã của bạn dùng một trường trong cột không được hỗ trợ, hãy sửa mã thay vì mong máy chủ bỏ qua nó. Tài liệu không nói từng trường không được hỗ trợ được xử lý ra sao, ngoại trừ speech, nơi các giá trị không được hỗ trợ trả về lỗi 400.

Tools và định dạng của định nghĩa tool

Cả native API lẫn endpoint chat tương thích OpenAI đều chấp nhận tools. Nếu bạn mô tả các tool theo dạng OpenAI, Tool Definition Checker trên trang này sẽ kiểm tra tên, mô tả và schema tham số theo định dạng đó trước khi bạn gửi đi.

Khi câu trả lời vẫn không phải JSON hợp lệ

Việc ràng buộc đầu ra nhằm mục đích cho bạn JSON hợp lệ, nhưng mã của bạn vẫn có thể nhận văn bản từ một mô hình khác, một phiên bản cũ hơn, hoặc từ một yêu cầu không có format. Công cụ bên dưới sửa các lỗi thường gặp như code fence, dấu phẩy thừa ở cuối và dấu nháy sai, đồng thời cảnh báo khi một lần sửa làm thay đổi ý nghĩa.

Dùng thử: LLM JSON Repair

Câu trả lời của mô hình hoặc JSON bị lỗi

Thụt lề2 dấu cách4 dấu cáchTabThu gọn

Chỉ áp dụng những cách sửa có đúng một đáp án rõ ràng. Mọi trường hợp khác được báo kèm vị trí thay vì bị đoán.

Mọi thứ chạy trong trình duyệt của bạn. Văn bản bạn dán không được tải lên.

Lưu ý về quyền truy cập

Ví dụ cục bộ trong tài liệu nói khóa API là bắt buộc nhưng bị bỏ qua. Cách đọc của chúng tôi, không phải lời khẳng định từ tài liệu: khóa này không bảo vệ máy chủ, vì vậy hãy giữ Ollama ở địa chỉ mặc định và đặt cơ chế xác thực phía trước nếu một máy khác cần truy cập.