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 10M 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 tùy chọn nhẹ hơn chỉ với các dependency của OpenAI:
# pip install "pydantic-ai-slim[openai]"

Ví dụ tối thiểu — agent qua Gonka. PydanticAI thiết lập custom endpoint 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(
    "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)

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

Tham số mô hình: cửa sổ ngữ cảnh của các mô hình trong mạng là 200K token (200000), độ dài phản hồi tối đa qua Gateway — lên tới 8192 token. Bạn có thể giới hạn đầu ra thông qua cài đặt mô hình (OpenAIChatModelSettings(max_tokens=8192)). Ngoài ra còn có moonshotai/Kimi-K2.6 và MiniMaxAI/MiniMax-M2.7 (mỗi mô hình hỗ trợ tới 8192 token đầu ra) — 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. Thay vì phân tích văn bản phản hồi bằng regex, bạn mô tả kết quả như một Pydantic model và truyền nó vào tham số output_type. Framework sử dụng tính năng tool calling của mô hình để ép nó trả về dữ liệu tuân thủ nghiêm ngặt theo schema, xác thực chúng và trả về đố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(
    "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'] — đây là list[str], không phải văn bản

Điều này hoạt động vì cả hai mô hình Gonka (Kimi K2.6 và MiniMax M2.7) đều hỗ trợ tool calling gốc — 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 kiểu hóa (typed object), không phải một chuỗi cần phân tích thủ công. Hoàn hảo 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 xử lý tiếp trong code theo đị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 yêu cầu. Ở đây, chi phí token quyết định liệu dự án sẽ chỉ dừng lại ở bản mẫu hay được đưa vào production. Hãy so sánh các khối lượng công việc điển hình:

Sự khác biệt lên tới hàng trăm, hàng ngàn lần. Đối với bản mẫu, điều này có nghĩa là 10M tokens miễn phí đủ cho hàng trăm lần chạy agent. Đối với production xử lý hàng trăm ngàn yêu cầu mỗi ngày, số tiền tiết kiệm được lên tới hàng chục ngàn đô la mỗi tháng — vẫn cùng một đoạn code 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à định dạng Anthropic (/v1/messages) — nhưng đối với PydanticAI, bạn chỉ cần endpoint tương thích OpenAI như đã hiển thị ở trên.

Khả năng quan trọng thứ hai của PydanticAI là các công cụ. Bạn có thể đăng ký một hàm bằng decorator @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 cần 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-your-key",
    ),
)

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


@agent.tool_plain
def roll_dice() -> str:
    """Gieo xúc xắc 6 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 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ì tool calling tại Gonka là native, các công cụ được gọi một cách đáng tin cậy — mà không cần phân tích phản hồi văn bản dễ bị lỗi. Toàn bộ chu trình (truy vấn → gọi tool → phản hồi cuối cùng) có chi phí khoảng $0.00007 qua Gonka so với $0.04–0.22 của OpenAI/Anthropic.

Chọn mô hình nào: moonshotai/Kimi-K2.6 — mạnh về coding và suy luận phức tạp, output lên tới 8192. MiniMaxAI/MiniMax-M2.7 — cho các cuộc hội thoại dài và những tác vụ cân bằng, output lên tới 8192. Cả hai đều có sẵn ngay lập tức với một key duy nhất — chỉ cần thay đổi dòng mô hình. Các công cụ tương tự: LangChain cho các chuỗi và RAG, LlamaIndex để lập chỉ mục dữ liệu.