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 lấy khóa: đăng ký tại gate.joingonka.ai/register — chúng tôi tặng 3M token miễn phí khi đăng ký — và tạo khóa jg-xxx trong Dashboard → API Keys.

Cài đặt:

pip install pydantic-ai
# hoặc bản rút gọn chỉ với các phụ thuộc của OpenAI:
# pip install "pydantic-ai-slim[openai]"

Ví dụ tối giản — sử dụng agent thông qua Gonka. PydanticAI thiết lập một endpoint tùy chỉnh thông qua OpenAIProvider(base_url=..., api_key=...), được chuyể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(
    "MiniMaxAI/MiniMax-M2.7",
    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)

Chỉ có vậy thôi — agent PydanticAI của bạn hoạt động qua mạng lưới phi tập trung Gonka với chi phí cực thấp. Phương thức run_sync tiện lợi cho các script; đối với code bất đồng bộ (async), hãy sử dụng await agent.run(...).

Thông số mô hình: Cửa sổ ngữ cảnh (context window) của MiniMax M2.7 là 200K token (200000), DeepSeek V4 Flash là 380K, GLM-5.3 Flash là 390K; độ dài phản hồi tối đa thông qua Gateway là 8192 token cho MiniMax và GLM-5.3 Flash, 32768 cho DeepSeek. Bạn có thể giới hạn đầu ra thông qua cài đặt mô hình (OpenAIChatModelSettings(max_tokens=8192)). Các mô hình MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 và zai-org/GLM-5.3-Flash đều khả dụng — 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à structured output (đầu ra có cấu trúc). Thay vì phân tích văn bản phản hồi bằng regex, 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 tool calling của mô hình để bắt nó trả về dữ liệu đúng theo schema, xác thực và trả lại đối tượng đã hoàn thiện 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(
    "MiniMaxAI/MiniMax-M2.7",
    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 là backend-developer, 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ì cả ba mô hình của Gonka (MiniMax M2.7, DeepSeek V4 Flash và GLM-5.3 Flash) đều hỗ trợ native tool calling — PydanticAI dựa vào đó để 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, không phải chuỗi văn bản cần phải xử lý thủ công. Rất lý tưởng cho việc trích xuất dữ liệu, phân loại, điền biểu mẫu và các pipeline RAG, nơi kết quả cần được tiếp tục xử lý trong mã nguồn với định dạng nghiêm ngặt.

PydanticAI là framework cho các agent và pipeline hoạt động liên tục: trích xuất dữ liệu, gọi công cụ, xử lý luồng request. Tại đây, chi phí token quyết định việc dự án sẽ chỉ là bản prototype hay đi vào production. Hãy so sánh các tải công việc điển hình:

Sự khác biệt là hàng trăm và hàng ngàn lần. Đối với prototype, điều này có nghĩa là 3M token miễn phí là đủ cho những lần chạy thử nghiệm đầu tiên. Đối với production xử lý hàng trăm ngàn request mỗi ngày, mức tiết kiệm lên tới hàng chục ngàn đô la mỗi tháng — với cùng một code trên PydanticAI, chỉ cần thay đổi base_url.

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

Khả năng quan trọng thứ hai của PydanticAI là các công cụ (tools). 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). Bản thân mô hình quyết định thời điểm gọi công cụ, nhận kết quả và tiếp tục suy 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-ваш-ключ",
    ),
)

agent = Agent(
    model,
    instructions="Ты помощник. Используй инструменты, когда нужно.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Бросает шестигранный кубик и возвращает результат."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Вычисляет математическое выражение."""
    return str(eval(expression))


result = agent.run_sync("Брось кубик и умножь результат на 7")
print(result.output)

Vì tool calling tại Gonka là native, 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 một cách mong manh. Toàn bộ chu kỳ (yêu cầu → gọi tool → phản hồi cuối cùng) có giá khoảng $0.00007 thông qua Gonka so với $0.04–0.22 tại OpenAI/Anthropic.

Cách chọn mô hình: MiniMaxAI/MiniMax-M2.7 — cho các cuộc hội thoại dài và các tác vụ cân bằng, đầu ra lên tới 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — một trong những ngữ cảnh dài nhất mạng lưới (380K) và các prompt lớn giá rẻ, đầu ra lên tới 32768. zai-org/GLM-5.3-Flash — mô hình reasoning cho các suy luận phức tạp và ngữ cảnh dài nhất mạng lưới (390K), đầu ra lên tới 8192; các lập luận tiêu tốn một phần max_tokens, hãy đặt nó với dự phòng (từ 600). Cả ba đều có sẵn ngay bây giờ chỉ với một khóa — chỉ cần thay đổi dòng mô hình. Các công cụ có tinh thần tương tự: LangChain cho chuỗi và RAG, LlamaIndex để lập chỉ mục dữ liệu.