BroadRouter

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

Cập nhật

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

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

Kết nối

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

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:

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.

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

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

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