PydanticAI + Gonka — các tác nhân AI có kiểu dữ liệu với chi phí thấp

Trước tiên, hãy nhận khóa của bạn: đăng ký tại gate.joingonka.ai/register — khi đăng ký, chúng tôi cung cấp 10 triệu token miễn phí — và tạo khóa jg-xxx trong Dashboard → API Keys.

Cài đặt:

pip install pydantic-ai
# hoặc biến thể nhẹ hơn chỉ với các phụ thuộc OpenAI:
# pip install "pydantic-ai-slim[openai]"

Một ví dụ tối thiểu — tác nhân thông qua Gonka. PydanticAI đặt một điểm cuối tùy chỉnh thông qua OpenAIProvider(base_url=..., api_key=...), được truyền vào OpenAIChatModel:

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-khóa-của-bạn",
    ),
)

agent = Agent(model)

result = agent.run_sync("Giải thích PoUW là gì trong hai câu")
print(result.output)

Đó là tất cả — tác nhân PydanticAI của bạn hoạt động thông qua mạng Gonka phi tập trung với chi phí thấp. Phương thức run_sync tiện lợi cho các tập lệnh; đối với mã async, có await agent.run(...).

Tham số mô hình: cửa sổ ngữ cảnh của Qwen3-235B là 128K token (131072), độ dài đầu ra tối đa thông qua Gateway là lên đến 8192 token. Đầu ra có thể được giới hạn thông qua cài đặt mô hình (OpenAIChatModelSettings(max_tokens=8192)). Cũng có sẵn moonshotai/Kimi-K2.6 (tối đa 3072 token đầu ra) và MiniMaxAI/MiniMax-M2.7 (tối đa 4096) — chỉ cần thay đổi tên mô hình trong đối số đầu tiên của OpenAIChatModel.

Lý do chính để chọn PydanticAI là đầu ra có cấu trúc (structured output). Thay vì phân tích văn bản phản hồi bằng biểu thức chính quy, bạn mô tả kết quả dưới dạng mô hình Pydantic và truyền nó vào tham số output_type. Framework sử dụng gọi công cụ của mô hình để buộc nó trả về dữ liệu tuân thủ nghiêm ngặt theo lược đồ, xác thực chúng và trả về một đối tượng đã sẵn sàng thông qua result.output.

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-khóa-của-bạn",
    ),
)


class Profile(BaseModel):
    name: str
    role: str
    skills: list[str]


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Trích xuất dữ liệu: Anna — nhà phát triển backend, biết Python, Go và Postgres"
)
print(result.output)
# name='Anna' role='backend-developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — đã là list[str], không phải văn bản

Điều này hoạt động vì Qwen3-235B (và hai mô hình Gonka khác) hỗ trợ gọi công cụ gốc — PydanticAI dựa vào nó để trả về cấu trúc JSON hợp lệ. Đầu ra bạn nhận được là một đối tượng Python được định kiểu, chứ không phải một chuỗi cần phải phân tích thủ công. Lý tưởng để trích xuất dữ liệu, phân loại, điền biểu mẫu và các đường ống RAG, nơi kết quả phải được chuyển tiếp trong mã theo một định dạng nghiêm ngặt.

PydanticAI là một framework dành cho các tác nhân và đường ống hoạt động liên tục: trích xuất dữ liệu, gọi công cụ, xử lý các luồng yêu cầu. Trong trường hợp này, chi phí token quyết định liệu một dự án có vẫn là một nguyên mẫu hay sẽ đi vào sản xuất. Chúng ta hãy so sánh các tải điển hình:

Sự khác biệt là hàng trăm đến hàng nghìn lần. Đối với một nguyên mẫu, điều này có nghĩa là 10M token miễn phí đủ cho hàng trăm lần chạy tác nhân. Đối với sản xuất, xử lý hàng trăm nghìn yêu cầu mỗi ngày, khoản tiết kiệm là hàng chục nghìn đô la mỗi tháng — với cùng mã PydanticAI, chỉ khác base_url.

Một khóa jg-xxx và một số dư hoạt động cho cả định dạng OpenAI (/v1) và định dạng Anthropic (/v1/messages) — nhưng đối với PydanticAI, một điểm cuối tương thích OpenAI, như hiển thị ở trên, là đủ.

Khả năng quan trọng thứ hai của PydanticAI là công cụ. Một hàm có thể được đăng ký bằng trình trang trí @agent.tool_plain (không có ngữ cảnh) hoặc @agent.tool (có quyền truy cập vào RunContext và dependency injection). Mô hình tự quyết định khi nào gọi công cụ, nhận kết quả và tiếp tục lập luận:

import random
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-khóa-của-bạn",
    ),
)

agent = Agent(
    model,
    instructions="Bạn là một trợ lý. Hãy sử dụng các công cụ khi cần.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Gieo một viên xúc xắc sáu mặt và trả về kết quả."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Tính toán một biểu thức toán học."""
    return str(eval(expression))


result = agent.run_sync("Gieo xúc xắc và nhân kết quả với 7")
print(result.output)

Vì gọi công cụ của Gonka là gốc, các công cụ được gọi một cách đáng tin cậy — không cần phân tích cú pháp phản hồi văn bản dễ vỡ. Toàn bộ chu trình (yêu cầu → gọi công cụ → phản hồi cuối cùng) có giá khoảng 0.00001 đô la thông qua Gonka so với 0.04–0.22 đô la của OpenAI/Anthropic.

Nên chọn mô hình nào: Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 — mặc định, cân bằng tốt nhất về chất lượng và giới hạn đầu ra lớn nhất (8192). moonshotai/Kimi-K2.6 mạnh về mã hóa và lý luận phức tạp (đầu ra lên đến 3072). MiniMaxAI/MiniMax-M2.7 — cho các cuộc đối thoại dài (đầu ra lên đến 4096). Cả ba đều có sẵn ngay bây giờ với một khóa — chỉ cần thay đổi chuỗi mô hình. Các công cụ tương tự: LangChain cho chuỗi và RAG, LlamaIndex để lập chỉ mục dữ liệu.