Tool calling (gọi công cụ) là thứ biến một model thành agent. Với model mở trên API tương thích OpenAI, định dạng request giống hệt khi bạn dùng OpenAI. Điểm khác là mức độ thường xuyên xảy ra lỗi và những gì server làm để ngăn lỗi. Bài này trình bày định dạng, cách viết schema mà model mở xử lý tốt, gọi song song, năm kiểu lỗi bạn sẽ thực sự gặp, và một vòng lặp Python chịu được các lỗi đó.
Tool calling hoạt động thế nào trên API tương thích OpenAI?
- Bạn gửi
messageskèm danh sáchtools. Mỗi công cụ có tên, mô tả và một JSON Schema cho tham số. - Model trả lời với
finish_reason: "tool_calls"và danh sáchtool_calls. Mỗi mục cóid, tên hàm vàargumentsdưới dạng chuỗi JSON. - Code của bạn chạy từng lệnh gọi và thêm một tin nhắn
role: "tool"cho mỗi lệnh, kèmtool_call_idtương ứng. - Bạn gọi API lần nữa. Model trả lời hoặc yêu cầu thêm công cụ.
Model không bao giờ tự chạy thứ gì. Code của bạn quyết định chạy cái gì.
Nên viết schema công cụ thế nào?
Model mở tuân theo schema đơn giản ổn định hơn. Các quy tắc sau đến từ hướng dẫn của OpenAI và từ những chỗ hay hỏng:
- Đặt tên công cụ theo hành động, như
read_filehaysearch_code, và nói rõ trong mô tả khi nào dùng từng công cụ. - Giữ danh sách ngắn. Hướng dẫn của OpenAI coi việc có dưới 20 hàm ở đầu mỗi lượt là một gợi ý mềm. Mọi schema cũng được gửi kèm trong mỗi lần gọi; xem ngân sách token của agent.
- Ưu tiên tham số phẳng. Chuỗi, số, boolean và enum. Tránh lồng sâu và object tự do.
- Dùng enum cho các lựa chọn cố định, để model không thể bịa ra giá trị. Công cụ tạo JSON schema biến một object tham số mẫu thành schema phẳng bạn có thể dán vào
parameters. - Đánh dấu trường bắt buộc. Chế độ strict của OpenAI yêu cầu
additionalProperties: falsevà mọi trường đều nằm trongrequired, vớinulllà một kiểu cho các trường tùy chọn. Việc nhà cung cấp có thực thistricthay không là khác nhau, nên dù sao cũng hãy validate.
Còn gọi công cụ song song thì sao?
Model có thể trả về nhiều mục trong tool_calls trong một lượt, ví dụ ba lần đọc file. Hãy chạy đồng thời các lệnh gọi độc lập và trả về một kết quả cho mỗi tool_call_id, theo thứ tự nào cũng được. Nếu công cụ của bạn có tác dụng phụ phụ thuộc lẫn nhau, hãy đặt parallel_tool_calls: false; hướng dẫn của OpenAI cho biết khi đó model chỉ gọi không hoặc một lần mỗi lượt. Hãy test xem nhà cung cấp có tôn trọng thiết lập này không.
Vì sao tool call thất bại?
| Lỗi | Bạn thấy gì | Cách sửa |
|---|---|---|
| Tham số sai định dạng | json.loads gây exception |
Trả lỗi parse dưới dạng kết quả công cụ; retry |
| Không khớp schema | Thiếu trường, sai kiểu, enum bịa ra | Validate; trả về lỗi validate |
| Công cụ không tồn tại | Một cái tên bạn chưa từng định nghĩa | Trả về “unknown tool, available: …” |
| Không gọi khi cần gọi | Trả lời bằng văn bản | tool_choice: "required" hoặc chỉ định hàm |
| Lệnh gọi bị cắt | finish_reason: "length" |
Tăng max_tokens; suy luận dùng chung giới hạn này |
Hai lỗi đầu là chuyện được dự liệu, không hiếm. Tài liệu tool calling của vLLM cho biết ở chế độ auto, trừ khi công cụ đặt strict: true (hoặc server áp một mức strict tối thiểu) và parser của model hỗ trợ ràng buộc, “vLLM extracts tool calls from raw text, so arguments may occasionally be malformed or violate the function’s parameter schema.” (bản dịch: vLLM trích tool call từ văn bản thô, nên tham số đôi khi có thể sai định dạng hoặc vi phạm schema tham số của hàm.) Chỉ định một hàm cụ thể sẽ dùng backend đầu ra có cấu trúc của vLLM. Nhà cung cấp của bạn có thể phục vụ model theo cách khác, nên hãy coi validate là bắt buộc.
Hàng cuối hay làm khó người dùng model suy luận. GLM 5.3 và Qwen3.8 27B suy nghĩ trước khi trả lời, và phần thinking được tính vào max_tokens. Vì sao phản hồi rỗng hoặc bị cắt giải thích nên chừa bao nhiêu chỗ.
Vòng lặp công cụ có validate và retry
import json, os
from openai import OpenAI
from jsonschema import validate, ValidationError
client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"], max_retries=4)
MODEL = "broadnet/glm-5.3"
TOOLS = [{"type": "function", "function": {
"name": "get_order_status",
"description": "Look up one order by its ID. Use when the user asks where an order is.",
"parameters": {"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"], "additionalProperties": False}}}]
SCHEMAS = {t["function"]["name"]: t["function"]["parameters"] for t in TOOLS}
IMPL = {"get_order_status": lambda order_id: f"Order {order_id}: shipped"}
def run_call(call):
name = call.function.name
if name not in IMPL:
return f"Error: unknown tool {name}. Available: {', '.join(IMPL)}"
try:
args = json.loads(call.function.arguments or "{}")
validate(args, SCHEMAS[name])
except (json.JSONDecodeError, ValidationError) as e:
return f"Error: invalid arguments ({e}). Send the call again with valid JSON."
return str(IMPL[name](**args))
def agent(messages, max_steps=8):
for _ in range(max_steps):
r = client.chat.completions.create(model=MODEL, messages=messages,
tools=TOOLS, max_tokens=4000)
msg = r.choices[0].message
if r.choices[0].finish_reason == "length":
raise RuntimeError("Output limit reached; raise max_tokens")
messages.append(msg.model_dump(exclude_none=True))
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
messages.append({"role": "tool", "tool_call_id": call.id,
"content": run_call(call)})
raise RuntimeError("Step limit reached")
Ba lựa chọn thiết kế quan trọng ở đây:
- Lỗi được trả về model dưới dạng kết quả công cụ. Model thấy chỗ sai và thường sửa ở lượt tiếp theo. Gây exception là vứt bỏ cơ hội đó.
- Vòng lặp có giới hạn.
max_stepsdừng một model cứ gọi công cụ mãi mà không tiến triển. - Retry ở tầng truyền tải là chuyện riêng.
max_retriestrên client xử lý 429 và 5xx. Tham số sai được xử lý trong vòng lặp. Đừng trộn lẫn hai việc; xem lỗi và retry.
Với công cụ có tác dụng phụ, như gửi email, hãy thêm idempotency key để một bước được retry không hành động hai lần. Agent chạy dài trình bày chuyện này.
Model nào của BroadNet hỗ trợ tool calling?
| Model | Có liệt kê công cụ | Context | Ghi chú |
|---|---|---|---|
| GLM 5.3 | Có | 1.048.576 | Có cả đầu ra có cấu trúc |
| Qwen3.8 27B | Có | 262.144 | Có cả đầu vào ảnh |
| DeepSeek V4.1 Flash | Không liệt kê | 1.048.576 | Nhận ảnh đầu vào; test công cụ trước khi dựa vào |
| Gemma 4 VL 26B | Không liệt kê | 32.768 | Không dùng cho vòng lặp công cụ |
Để chọn giữa hai model hỗ trợ công cụ, xem GLM 5.3 và Qwen3.8 27B. Khi câu trả lời cuối cần theo một cấu trúc nhưng không cần chạy hàm nào, đầu ra có cấu trúc đơn giản hơn dùng công cụ.
BroadNet Inference phù hợp ở đâu?
BroadNet Inference phục vụ GLM 5.3 và Qwen3.8 27B có liệt kê tool calling, qua định dạng chat completions chuẩn, nên vòng lặp ở trên chạy nguyên vẹn với OpenAI Python SDK. Giá mỗi token có trên trang giá. Dịch vụ không host công cụ phía server như tìm kiếm web hay chạy code, và tài liệu không liệt kê tool calling cho DeepSeek V4.1 Flash, model của các gói không giới hạn. Với agent dùng nhiều công cụ, hãy dùng GLM 5.3 hoặc Qwen3.8 27B theo token. Nếu bạn vẫn muốn dùng gói giá cố định, hãy kiểm tra trong một giờ Meteor giá $1 rằng DeepSeek V4.1 Flash gọi công cụ của bạn ổn định trước khi mua gói tháng.
