---
title: "Pydantic AI với base_url tương thích OpenAI tùy chỉnh"
description: "Chạy agent Pydantic AI trên BroadNet Inference với OpenAIChatModel và OpenAICompatibleProvider, kèm gọi tool, đầu ra có cấu trúc và chỉnh model profile."
url: https://broadrouter.com/vi/guides/pydantic-ai-openai-compatible/
lang: vi
updated: 2026-11-16
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/guides/pydantic-ai-openai-compatible/) (cập nhật ngày 2026-11-16).

# Dùng Pydantic AI với BroadNet Inference (OpenAICompatibleProvider)

Cập nhật 2026-11-16

Cài pydantic-ai-slim\[openai\], rồi tạo OpenAIChatModel với model ID BroadNet như broadnet/glm-5.3 và một OpenAICompatibleProvider có base URL https://inference.broadnet.ai/v1 cùng key BroadNet. Truyền model đó cho Agent. Hãy dùng OpenAIChatModel, không dùng model Responses, vì BroadNet phục vụ chat completions. Tài liệu Pydantic AI nói OpenAIProvider kèm base\_url là dành cho chính OpenAI.

Pydantic AI là framework agent cho Python do đội ngũ Pydantic phát triển. Với một dịch vụ không có provider sẵn có, tài liệu của nó khuyên dùng `OpenAICompatibleProvider` với `base_url` của dịch vụ đó. BroadNet Inference phục vụ chat completions chuẩn tại `https://inference.broadnet.ai/v1`, nên đó là con đường cần đi. BroadRouter là website của chính BroadNet; bài này làm theo tài liệu Pydantic AI tính đến phiên bản 2.68.

## Cài đặt

```bash
pip install "pydantic-ai-slim[openai]"
export BROADNET_API_KEY='your-broadnet-key'
```

## Kết nối

```python
import os
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai_compatible import OpenAICompatibleProvider

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider(
        'broadnet',
        base_url='https://inference.broadnet.ai/v1',
        api_key=os.environ['BROADNET_API_KEY'],
    ),
)

agent = Agent(model)
result = agent.run_sync('Give me three names for a Go linting tool.')
print(result.output)
```

Chạy đoạn này chính là phép thử: câu trả lời được in ra nghĩa là key, URL và model ID đều đúng.

-   **Đối số đầu tiên là model ID** được gửi tới BroadNet. Hãy dùng chính xác, kèm tiền tố `broadnet/`.
-   **Tên provider** (ở đây là `'broadnet'`) được ghi lại trên mọi phản hồi. Tài liệu Pydantic AI nói nên giữ tên này cố định, vì nó quyết định dữ liệu nào từ các phản hồi trước được gửi lại cho dịch vụ.
-   **Giữ nguyên `OpenAIChatModel`.** Tài liệu Pydantic AI nói chỉ dùng `OpenAIResponsesModel` nếu dịch vụ triển khai Responses API. BroadNet không liệt kê API này.

## Tool và đầu ra có cấu trúc

```python
from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str

agent = Agent(model, output_type=City)
print(agent.run_sync('Which city hosts the Burj Khalifa?').output)
```

Hãy dùng `broadnet/glm-5.3` hoặc `broadnet/qwen3.8-27b` cho tool và đầu ra có cấu trúc; tài liệu BroadNet chỉ ghi cả hai tính năng cho hai model này.

## Khi nào cần đặt model profile

Pydantic AI chọn profile cho request dựa trên tên model. Nếu một tính năng bị bỏ qua hoặc bị từ chối, tài liệu của nó khuyên truyền `OpenAIModelProfile` của riêng bạn. Có hai thiết lập đáng biết khi dùng BroadNet:

```python
from pydantic_ai.profiles.openai import OpenAIModelProfile

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider('broadnet', base_url='https://inference.broadnet.ai/v1', api_key=os.environ['BROADNET_API_KEY']),
    profile=OpenAIModelProfile(
        openai_chat_supports_max_completion_tokens=False,  # send max_tokens, the field BroadNet documents
        openai_supports_strict_tool_definition=False,      # only if strict tool schemas are rejected
    ),
)
```

Truyền giới hạn đầu ra qua model settings, ví dụ `agent.run_sync(prompt, model_settings={'max_tokens': 2000})`. Trên DeepSeek V4.1 Flash, GLM 5.3 và Qwen3.8 27B, phần suy luận được tính vào giới hạn này.

## Nên chọn model nào

| Agent | Model |
| --- | --- |
| Tool, đầu ra có cấu trúc | `broadnet/glm-5.3` |
| Hình ảnh hoặc văn bản tiếng Ả Rập, có tool | `broadnet/qwen3.8-27b` |
| Tài liệu dài, gói giá cố định | `broadnet/deepseek-v4.1-flash` |
| Tín dụng ban đầu miễn phí | `broadnet/gemma-4-26b-a4b` (context 32.768 token) |

[Giá của mọi model](https://broadrouter.com/vi/pricing/).

## Xử lý sự cố

-   **401.** Key bị sai, hết hạn hoặc hết hạn mức.
-   **404 hoặc không tìm thấy model.** `base_url` phải kết thúc bằng `/v1`. Kiểm tra model ID. Các model trả phí cần nạp tiền; tín dụng $5 chỉ dùng được cho `broadnet/gemma-4-26b-a4b` và hai model Transcribe.
-   **Đầu ra rỗng hoặc vòng lặp thử lại do lỗi kiểm tra hợp lệ.** Phần suy luận đã dùng hết ngân sách đầu ra. Hãy tăng `max_tokens`. [Vì sao câu trả lời trả về rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/).
-   **400 với định nghĩa tool.** Đặt `openai_supports_strict_tool_definition=False` trong profile, và dùng model mà BroadNet ghi hỗ trợ tool.
-   **429 khi chạy nhiều agent đồng thời.** Key trả theo mức dùng cho phép 30 request mỗi phút và 4 request đang xử lý. Xem [lỗi và thử lại](https://broadrouter.com/vi/guides/errors-and-retries/).

## Thuật ngữ trong hướng dẫn này

[Đầ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ể.

[Trả theo mức dùng (pay-as-you-go)](https://broadrouter.com/vi/glossary/pay-as-you-go/)

Trả theo mức dùng (pay-as-you-go) là mô hình giá mà bạn chỉ trả cho những gì đã dùng, đo theo đơn vị như token, request hoặc phút âm thanh, không có gói đăng ký hay cam kết tối thiểu. Hầu hết API LLM tính phí theo cách này, trừ vào số dư trả trước hoặc qua hóa đơn định kỳ.

[Giới hạn tần suất (rate limit)](https://broadrouter.com/vi/glossary/rate-limit/)

Giới hạn tần suất (rate limit) là mức trần mà API đặt ra cho lượng sử dụng của một client trong một khoảng thời gian, như số request mỗi phút hoặc số token mỗi phút. Request vượt giới hạn bị từ chối, thường với HTTP 429 Too Many Requests, cho đến khi mức dùng giảm xuống dưới giới hạn.

[Chat Completions API](https://broadrouter.com/vi/glossary/chat-completions-api/)

Chat Completions API là endpoint HTTP của OpenAI, POST /v1/chat/completions, nhận tên model và danh sách message có gắn vai trò rồi trả về message tiếp theo của model. Cấu trúc request và response của nó đã trở thành định dạng chung mà các nhà cung cấp và SDK tương thích OpenAI dùng lại.

[Concurrency (request đồng thời)](https://broadrouter.com/vi/glossary/concurrency/)

Concurrency (request đồng thời) là số request mà một client đang xử lý cùng lúc. Các API LLM thường giới hạn nó theo key hoặc theo gói, tách biệt với số request mỗi phút, vì mỗi request đang mở chiếm dụng năng lực GPU cho tới khi response kết thúc.

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

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

### Với BroadNet nên dùng OpenAIProvider hay OpenAICompatibleProvider?

OpenAICompatibleProvider. Tài liệu Pydantic AI nói OpenAIProvider cũng nhận base\_url, nhưng nó dành cho chính OpenAI hoặc một proxy trong suốt tới OpenAI, và nó giả định model cùng tính năng của OpenAI.

### Vì sao dùng OpenAIChatModel mà không dùng model OpenAI mặc định?

Model OpenAI mặc định của Pydantic AI dùng Responses API. BroadNet phục vụ chat completions tại /v1/chat/completions, chính là endpoint mà OpenAIChatModel gọi.

### Tool và đầu ra có cấu trúc có hoạt động không?

Có, trên các model BroadNet ghi hỗ trợ tool và đầu ra có cấu trúc là GLM 5.3 và Qwen3.8 27B. Tài liệu BroadNet không ghi hỗ trợ tool cho DeepSeek V4.1 Flash, nên hãy thử trước các agent dùng tool trên model này.

### Làm sao để Pydantic AI không gửi max\_completion\_tokens?

Truyền profile=OpenAIModelProfile(openai\_chat\_supports\_max\_completion\_tokens=False) cho OpenAIChatModel. Khi đó Pydantic AI gửi trường max\_tokens cũ hơn, đúng trường mà tài liệu tham chiếu API của BroadNet mô tả.

## Hướng dẫn liên quan

-   [Dùng OpenAI Python SDK với BroadNet Inference](https://broadrouter.com/vi/guides/openai-python-sdk/)
-   [Dùng LangChain với BroadNet Inference](https://broadrouter.com/vi/guides/langchain-openai-base-url/)
-   [Dùng CrewAI với BroadNet Inference làm endpoint OpenAI tùy chỉnh](https://broadrouter.com/vi/guides/crewai-custom-openai-endpoint/)
-   [Vì sao model suy luận trả về câu trả lời rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/)
-   [Mọi công cụ dùng được với BroadNet Inference (tiếng Anh)](https://broadrouter.com/integrations/): SDK, agent lập trình, giao diện chat và công cụ tự động hóa, kèm cấu hình chính xác cho từng công cụ

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-guides-pydantic-ai-openai-compatible&utm_content=page-cta) ·

**Nguồn**

-   [Tài liệu Pydantic AI, các API tương thích khác (Other endpoints, Model profile) (kiểm tra ngày 2026-11-15)](https://pydantic.dev/docs/ai/models/compatible-apis/)
-   [Tài liệu Pydantic AI, model OpenAI (kiểm tra ngày 2026-11-15)](https://pydantic.dev/docs/ai/models/openai/)
-   [PyPI, pydantic-ai 2.68.0, Python 3.11 trở lên (kiểm tra ngày 2026-11-15)](https://pypi.org/project/pydantic-ai/)
-   [Tài liệu tham chiếu API BroadNet Inference (kiểm tra ngày 2026-11-15) (tiếng Anh)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-guides-pydantic-ai-openai-compatible&utm_content=sources)
