BroadRouter
Bắt đầu

Tool calling với model mở: schema, gọi song song, retry

Đội ngũ BroadNet Inference · 4 phút đọc · Đăng ngày · Cập nhật

Model mở trên API tương thích OpenAI dùng cùng định dạng tools và tool_calls như OpenAI. Hãy giữ schema nhỏ và phẳng, parse tham số như chuỗi JSON, validate trước khi chạy bất cứ thứ gì, và trả lỗi về cho model dưới dạng kết quả công cụ để nó thử lại. Hãy giới hạn số bước. Trên BroadNet, GLM 5.3 và Qwen3.8 27B có liệt kê hỗ trợ công cụ.

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?

  1. Bạn gửi messages kèm danh sách tools. Mỗi công cụ có tên, mô tả và một JSON Schema cho tham số.
  2. Model trả lời với finish_reason: "tool_calls" và danh sách tool_calls. Mỗi mục có id, tên hàm và arguments dưới dạng chuỗi JSON.
  3. 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èm tool_call_id tương ứng.
  4. 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_file hay search_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: false và mọi trường đều nằm trong required, với null là một kiểu cho các trường tùy chọn. Việc nhà cung cấp có thực thi strict hay 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:

  1. 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 đó.
  2. Vòng lặp có giới hạn. max_steps dừng một model cứ gọi công cụ mãi mà không tiến triển.
  3. Retry ở tầng truyền tải là chuyện riêng. max_retries trê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.

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

Model mở có hỗ trợ function calling không?

Nhiều model có, nhưng mức hỗ trợ phụ thuộc vào model và cách nhà cung cấp phục vụ nó. Trên BroadNet Inference, tài liệu liệt kê tool calling cho GLM 5.3 và Qwen3.8 27B. Tài liệu không liệt kê cho DeepSeek V4.1 Flash hay Gemma 4 VL 26B.

Vì sao tham số tool call của tôi là JSON không hợp lệ?

Trừ khi server ràng buộc quá trình giải mã, tham số được sinh ra dưới dạng văn bản rồi mới parse. Tài liệu vLLM nói tham số trích từ văn bản thô đôi khi có thể sai định dạng. Hãy bắt lỗi parse và gửi nó về dưới dạng kết quả công cụ để model tự sửa.

Làm sao tắt gọi công cụ song song?

Trong định dạng OpenAI, đặt parallel_tool_calls là false. Khi đó model chỉ gọi không hoặc một công cụ mỗi lượt. Hãy kiểm tra nhà cung cấp của bạn có tôn trọng trường này không.

Vì sao model trả lời bằng văn bản thay vì gọi công cụ?

Với tool_choice auto, model tự quyết định. Hãy đặt tool_choice là required, hoặc chỉ định một hàm cụ thể, khi bắt buộc phải gọi. Cũng hãy kiểm tra mô tả công cụ có nói khi nào cần dùng không.

Vì sao tool call của tôi bị cắt giữa chừng?

Model suy luận tính phần thinking vào max_tokens. Giới hạn nhỏ có thể khiến phản hồi dừng giữa phần tham số. Hãy kiểm tra finish_reason và tăng max_tokens.

Đọc dạng MarkdownHỏi ChatGPTHỏi ClaudeHỏi Perplexity