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

Đầu tiên, hãy lấy API key: đăng ký tại gate.joingonka.ai/register — khi đăng ký bạn được tặng 3M token miễn phí — rồi tạo key jg-xxx trong Dashboard → API Keys.

Cài đặt:

pip install pydantic-ai
# or the slim variant with only the OpenAI dependencies:
# pip install "pydantic-ai-slim[openai]"

Ví dụ tối giản — một agent chạy qua Gonka. PydanticAI thiết lập endpoint tùy chỉnh thông qua OpenAIProvider(base_url=..., api_key=...), rồi 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(
    "MiniMaxAI/MiniMax-M2.7",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-your-key",
    ),
)

agent = Agent(model)

result = agent.run_sync("Explain in two sentences what PoUW is")
print(result.output)

Vậy là xong — agent PydanticAI của bạn đã chạy qua mạng phi tập trung Gonka với chi phí cực rẻ. Phương thức run_sync rất tiện cho script; với code async thì dùng await agent.run(...).

Thông số model: cửa sổ ngữ cảnh của MiniMax M2.7 là 180K token (180000), DeepSeek V4 Flash là 380K, GLM-5.3 Flash là 390K; độ dài phản hồi tối đa qua Gateway lên tới 8192 token với MiniMax và GLM-5.3 Flash, và tới 32768 với DeepSeek. Bạn có thể giới hạn output qua cài đặt model (OpenAIChatModelSettings(max_tokens=8192)). Hiện có sẵn MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 và zai-org/GLM-5.3-Flash — chỉ cần đổi tên model ở tham số đầu tiên của OpenAIChatModel.

Lý do chính để chọn PydanticAI là structured output. Thay vì dùng regex để bóc tách nội dung phản hồi, bạn mô tả kết quả dưới dạng một Pydantic model rồi truyền vào tham số output_type. Framework sẽ dùng tool calling của model để buộc nó trả về dữ liệu đúng theo schema, xác thực dữ liệu đó và đưa cho bạn một object hoàn chỉnh 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-your-key",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "Extract the data: Anna is a backend developer who knows Python, Go and Postgres"
)
print(result.output)
# name='Anna' role='backend developer' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — already a list[str], not text

Điều này hoạt động được vì cả ba model của Gonka (MiniMax M2.7, DeepSeek V4 Flash và GLM-5.3 Flash) đều hỗ trợ tool calling gốc — PydanticAI dựa vào đó để trả về cấu trúc JSON hợp lệ. Kết quả bạn nhận được là một object Python có kiểu rõ ràng, chứ không phải một chuỗi phải tự xử lý thủ công. Cực kỳ phù hợp cho trích xuất dữ liệu, phân loại, điền form và các pipeline RAG, nơi kết quả cần đi tiếp trong code theo đúng đị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à tools. Bạn có thể đăng ký một hàm bằng decorator @agent.tool_plain (không có context) hoặc @agent.tool (có truy cập vào RunContext và dependency injection). Model tự quyết định khi nào gọi tool, nhận kết quả rồi 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-your-key",
    ),
)

agent = Agent(
    model,
    instructions="You are an assistant. Use the tools when needed.",
)


@agent.tool_plain
def roll_dice() -> str:
    """Rolls a six-sided die and returns the result."""
    return str(random.randint(1, 6))


@agent.tool_plain
def calculator(expression: str) -> str:
    """Evaluates a math expression."""
    return str(eval(expression))


result = agent.run_sync("Roll the die and multiply the result by 7")
print(result.output)

Vì tool calling của Gonka là gốc, các tool được gọi một cách đáng tin cậy — không cần bóc tách text phản hồi mong manh. Toàn bộ vòng lặp (request → gọi tool → phản hồi cuối) chỉ tốn khoảng $0.00007 qua Gonka, so với $0.04–0.22 ở OpenAI/Anthropic.

Nên chọn model nào: MiniMaxAI/MiniMax-M2.7 — cho hội thoại dài và các tác vụ cân bằng, output tới 8192. deepseek-ai/DeepSeek-V4-Flash-0731 — một trong những ngữ cảnh dài nhất của mạng lưới (380K) và prompt lớn giá rẻ, output tới 32768. zai-org/GLM-5.3-Flash — model reasoning cho các suy luận phức tạp và ngữ cảnh dài nhất mạng lưới (390K), output tới 8192; phần suy luận chiếm một phần max_tokens, nên đặt dư (từ 600 trở lên). Cả ba đều có sẵn ngay bây giờ với một key duy nhất — chỉ việc đổi dòng model. Các công cụ cùng tinh thần: LangChain cho chain và RAG, LlamaIndex cho lập chỉ mục dữ liệu.