---
title: "Tool calling với model mở: schema, retry và code mẫu"
description: "Function calling trên model mở tương thích OpenAI: mẹo viết schema, gọi công cụ song song, năm kiểu lỗi của tool call và một vòng lặp Python có validate và retry."
url: https://broadrouter.com/vi/blog/tool-calling-open-models/
lang: vi
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Được dịch từ tiếng Anh với sự hỗ trợ của AI. [Đọc bản gốc tiếng Anh](https://broadrouter.com/blog/tool-calling-open-models/) (cập nhật ngày 2026-11-16).

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

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

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ụ.

## Ý chính

-   Định dạng truyền giống hệt OpenAI: gửi vào danh sách tools, nhận về tool\_calls, rồi gửi một tin nhắn role tool cho mỗi tool\_call\_id.
-   Tham số đến dưới dạng chuỗi JSON. Tài liệu vLLM cảnh báo rằng khi trích tool call từ văn bản thô, chúng “may occasionally be malformed or violate the function's parameter schema” (bản dịch: đôi khi có thể sai định dạng hoặc vi phạm schema tham số của hàm).
-   Hãy validate mọi lần gọi, gửi lỗi về dưới dạng kết quả công cụ, và giới hạn số lần retry cũng như tổng số bước.
-   Ít công cụ hơn, phẳng hơn thì hoạt động tốt hơn. OpenAI gợi ý dưới 20 hàm ở đầu mỗi lượt.
-   Trên BroadNet Inference, hãy dùng GLM 5.3 hoặc Qwen3.8 27B cho tool calling; test DeepSeek V4.1 Flash trước khi dựa vào nó.

**Trong trang này**

1.  Tool calling hoạt động thế nào trên API tương thích OpenAI?
2.  Nên viết schema công cụ thế nào?
3.  Còn gọi công cụ song song thì sao?
4.  Vì sao tool call thất bại?
5.  Vòng lặp công cụ có validate và retry
6.  Model nào của BroadNet hỗ trợ tool calling?
7.  BroadNet Inference phù hợp ở đâu?

[Tool calling](https://broadrouter.com/vi/glossary/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](https://broadrouter.com/vi/glossary/openai-compatible-api/), đị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](https://broadrouter.com/vi/blog/agent-token-budget/).
-   **Ư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](https://broadrouter.com/tools/json-schema-generator/) 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](https://broadrouter.com/vi/glossary/reasoning-tokens/). 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`](https://broadrouter.com/vi/glossary/max-tokens/). [Vì sao phản hồi rỗng hoặc bị cắt](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/) giải thích nên chừa bao nhiêu chỗ.

## Vòng lặp công cụ có validate và retry

```python
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](https://broadrouter.com/vi/guides/errors-and-retries/).

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](https://broadrouter.com/vi/blog/long-running-agents-timeouts-retries/) 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](https://broadrouter.com/vi/models/glm-5.3/) | Có | 1.048.576 | Có cả đầu ra có cấu trúc |
| [Qwen3.8 27B](https://broadrouter.com/vi/models/qwen3.8-27b/) | Có | 262.144 | Có cả đầu vào ảnh |
| [DeepSeek V4.1 Flash](https://broadrouter.com/vi/models/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](https://broadrouter.com/vi/models/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](https://broadrouter.com/compare/glm-5.3-vs-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](https://broadrouter.com/vi/blog/structured-output-json-schema/) đơ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](https://broadrouter.com/vi/guides/openai-python-sdk/). Giá mỗi token có trên [trang giá](https://broadrouter.com/vi/pricing/). 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ông cụ miễn phí cho chủ đề này (tiếng Anh)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Công cụ miễn phí (tiếng Anh)](https://broadrouter.com/tools/)

## Thuật ngữ trong bài này

[Tool calling (gọi tool, function calling)](https://broadrouter.com/vi/glossary/tool-calling/)

Tool calling, còn gọi là function calling, là tính năng của API LLM trong đó model trả về một yêu cầu có cấu trúc để chạy một hàm do nhà phát triển định nghĩa, kèm đối số JSON. Ứng dụng chạy hàm rồi gửi kết quả lại; model không bao giờ tự chạy code.

[API tương thích OpenAI (OpenAI-compatible API)](https://broadrouter.com/vi/glossary/openai-compatible-api/)

API tương thích OpenAI là một HTTP API nhận cùng định dạng request và phản hồi như OpenAI API, ví dụ POST /v1/chat/completions, nên SDK và công cụ của OpenAI dùng được nó chỉ bằng cách đổi base URL, API key và tên model.

[vLLM](https://broadrouter.com/vi/glossary/vllm/)

vLLM là thư viện mã nguồn mở để chạy suy luận và phục vụ (serving) LLM, ban đầu được phát triển tại Sky Computing Lab của UC Berkeley. Nó quản lý bộ nhớ KV cache bằng PagedAttention, gom request liên tục theo continuous batching, hỗ trợ nhiều định dạng lượng tử hóa và cung cấp HTTP server tương thích OpenAI.

[Đầu ra có cấu trúc (structured output)](https://broadrouter.com/vi/glossary/structured-output/)

Đầu ra có cấu trúc (structured output) là tính năng của API LLM buộc câu trả lời của model theo định dạng do lập trình viên chỉ định, thường là JSON Schema, để code parse được tin cậy. Nó chặt hơn JSON mode, vốn chỉ đảm bảo JSON hợp lệ chứ không đảm bảo một cấu trúc cụ thể.

[Model trọng số mở (open-weight model)](https://broadrouter.com/vi/glossary/open-weight-model/)

Model trọng số mở (open-weight) là model học máy có trọng số đã huấn luyện được công bố để ai cũng tải về và chạy, thường kèm giấy phép có điều kiện. Nó khác AI mã nguồn mở hoàn toàn, vốn công bố thêm code huấn luyện và chi tiết dữ liệu huấn luyện để người khác tái tạo model.

[Token](https://broadrouter.com/vi/glossary/token/)

Token là đơn vị văn bản mà model ngôn ngữ đọc và viết: một từ, một phần của từ, một dấu câu hoặc một chuỗi byte do tokenizer của model tạo ra. API LLM đếm, giới hạn và thường tính phí theo token.

[Idempotency key (khóa idempotency)](https://broadrouter.com/vi/glossary/idempotency-key/)

Idempotency key là một giá trị duy nhất, thường là ID ngẫu nhiên như UUID, mà client gắn vào request làm thay đổi trạng thái, chẳng hạn thanh toán hay mua hàng. Nếu cùng request được gửi lại với cùng key, server trả về kết quả ban đầu thay vì thực hiện hai lần.

[JSON Schema](https://broadrouter.com/vi/glossary/json-schema/)

JSON Schema là một bộ từ vựng viết bằng JSON để mô tả và kiểm tra cấu trúc dữ liệu JSON: kiểu, trường bắt buộc, giá trị cho phép và cách lồng nhau. Phiên bản hiện tại là 2020-12. Các API LLM dùng nó để định nghĩa tham số tool và cấu trúc chính xác mà structured output phải theo.

## 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 tiếp

-   [OpenClaw và Hermes Agent với model giá rẻ: cài đặt và tính token](https://broadrouter.com/vi/blog/openclaw-hermes-agent-cheap-model/)
-   [JSON mode và json\_schema: đầu ra có cấu trúc đáng tin cậy](https://broadrouter.com/vi/blog/structured-output-json-schema/)
-   [Dùng MCP server với model tương thích OpenAI (mọi nhà cung cấp)](https://broadrouter.com/vi/blog/mcp-with-openai-compatible-models/)
-   [Agent chạy dài: timeout, retry và checkpoint đứng vững](https://broadrouter.com/vi/blog/long-running-agents-timeouts-retries/)
-   [Ngân sách token của agent: token trong vòng lặp agent đi đâu](https://broadrouter.com/vi/blog/agent-token-budget/)
-   [Phần cứng GPU và cách phục vụ model của BroadNet, theo lời BroadNet](https://broadrouter.com/vi/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache phản hồi API LLM để giảm chi phí: cache khớp chính xác (Python)](https://broadrouter.com/vi/blog/cache-llm-responses-cut-cost/)
-   [Hướng dẫn: Dùng OpenAI Python SDK với BroadNet Inference](https://broadrouter.com/vi/guides/openai-python-sdk/)
-   [Hướng dẫn: Chạy OpenAI Agents SDK trên BroadNet Inference](https://broadrouter.com/vi/guides/openai-agents-sdk-custom-provider/)
-   [Hướng dẫn: Vì sao model suy luận trả về câu trả lời rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/)
-   [Hướng dẫn: Mã lỗi BroadNet Inference và khi nào nên thử lại](https://broadrouter.com/vi/guides/errors-and-retries/)

Hãy thử với khối lượng công việc thực tế của bạn. Tài khoản mới được tặng US$5 tín dụng ban đầu cho Gemma và chuyển giọng nói thành văn bản. DeepSeek, GLM và Qwen3.8 cần nạp tiền.

[Bắt đầu](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-blog-tool-calling-open-models&utm_content=page-cta) ·

**Nguồn**

-   [OpenAI, hướng dẫn function calling (kiểm tra 2026-11-14)](https://developers.openai.com/api/docs/guides/function-calling)
-   [Tài liệu vLLM, tool calling (kiểm tra 2026-11-14)](https://docs.vllm.ai/en/latest/features/tool_calling/)
-   [Tài liệu API BroadNet Inference, các model (tiếng Anh)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-blog-tool-calling-open-models&utm_content=sources#models)
