PydanticAI + Gonka — 低成本的类型化 AI 代理

首先获取 API 密钥：在 gate.joingonka.ai/register 注册 — 注册时我们赠送 10M 免费 tokens — 并在 Dashboard → API Keys 中创建 jg-xxx 密钥。

安装：

pip install pydantic-ai
# 或者仅包含 OpenAI 依赖的轻量版：
# pip install "pydantic-ai-slim[openai]"

一个最小示例 — 通过 Gonka 使用 Agent。PydanticAI 通过 OpenAIProvider(base_url=..., api_key=...) 设置自定义端点，该端点被传递给 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-你的密钥",
    ),
)

agent = Agent(model)

result = agent.run_sync("用两句话解释什么是 PoUW")
print(result.output)

这就完成了 — 你的 PydanticAI agent 通过 去中心化 Gonka 网络 以极低成本运行。run_sync 方法适合脚本；对于异步代码，可以使用 await agent.run(...)。

模型参数：网络模型的上下文窗口为 200K tokens (200000)，通过 Gateway 的最大回复长度最高可达 8192 tokens。你可以通过模型设置限制输出 (OpenAIChatModelSettings(max_tokens=8192))。此外还提供 moonshotai/Kimi-K2.6 和 MiniMaxAI/MiniMax-M2.7 (每个最大支持 8192 tokens 输出) — 只需更改 OpenAIChatModel 第一个参数中的模型名称即可。

选择 PydanticAI 的主要原因是 structured output。与其使用正则解析文本回复，不如将结果描述为 Pydantic 模型并将其传递给 output_type 参数。框架利用模型的功能调用 (tool calling) 强制其严格按模式返回数据，进行验证，并通过 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-你的密钥",
    ),
)


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


agent = Agent(model, output_type=Profile)

result = agent.run_sync(
    "提取数据：安娜是一名后端开发者，精通 Python, Go 和 Postgres"
)
print(result.output)
# name='安娜' role='后端开发者' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — 这已经是 list[str]，不是文本

之所以可行，是因为两个 Gonka 模型 (Kimi K2.6 和 MiniMax M2.7) 都支持原生 tool calling — PydanticAI 利用这一点返回有效的 JSON 结构。你得到的是一个类型化的 Python 对象，而不是需要手动解析的字符串。这非常适合数据提取、分类、表单填充和 RAG 流水线，其中结果需要在严格格式下在代码中进一步处理。

PydanticAI 是一个服务于持续运行的代理和流水线的框架，它们不断地提取数据、调用工具并处理请求流。在这里，token 成本决定了项目是停留在原型阶段还是进入生产部署。我们比较一下典型负载：

差异高达数百到数千倍。对于原型开发，10M 免费 tokens 足以运行数百次代理任务。对于每天处理数十万次请求的生产系统，使用相同的 PydanticAI 代码，只需更换 base_url，每月即可节省数万美元。

一个 jg-xxx 密钥和余额同时适用于 OpenAI 格式 (/v1) 和 Anthropic 格式 (/v1/messages)——但对于 PydanticAI，使用上述符合 OpenAI 标准的接口即可。

PydanticAI 的第二个核心功能是工具。函数可以通过 @agent.tool_plain 装饰器（无上下文）或 @agent.tool（具有对 RunContext 和依赖注入的访问权限）进行注册。模型会自动决定何时调用工具、接收结果并继续推理：

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)

由于 Gonka 的 tool calling 是原生的，工具调用非常可靠——无需对文本响应进行脆弱的解析。整个周期（请求 → 工具调用 → 最终响应）通过 Gonka 仅需约 $0.00007，而 OpenAI/Anthropic 则需 $0.04–0.22。

模型选择：moonshotai/Kimi-K2.6 在编程和复杂推理方面表现出色，输出上限 8192。MiniMaxAI/MiniMax-M2.7 适合长对话和均衡任务，输出上限 8192。两者目前都可通过同一密钥使用——只需更改模型字符串即可。思路类似的工具：用于链式调用和 RAG 的 LangChain，用于数据索引的 LlamaIndex。