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

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

安装：

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

一个最小示例 — 通过 Gonka 使用 Agent。PydanticAI 通过 OpenAIProvider(base_url=..., api_key=...) 设置自定义 endpoint，并将其传递给 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(...)。

模型参数：MiniMax M2.7 的上下文窗口为 200K token (200000)，DeepSeek V4 Flash 为 380K，GLM-5.3 Flash 为 390K；通过 Gateway 的最大输出长度对于 MiniMax 和 GLM-5.3 Flash 可达 8192 token，对于 DeepSeek 则可达 32768 token。可以通过模型设置 (OpenAIChatModelSettings(max_tokens=8192)) 来限制输出。目前可用模型包括 MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731 和 zai-org/GLM-5.3-Flash — 只需更改 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 模型（MiniMax M2.7、DeepSeek V4 Flash 和 GLM-5.3 Flash）都支持原生 tool calling — PydanticAI 依靠此功能返回有效的 JSON 结构。你得到的是一个类型化的 Python 对象，而不是需要手动解析的字符串。这非常适合数据提取、分类、表单填充以及在 RAG 流水线中使用，其中结果需要以严格格式继续参与代码流程。

PydanticAI 是一个用于连续运行的智能体和流水线的框架：它们提取数据、调用工具并处理请求流。在这里，token 成本决定了项目是仅仅维持在原型阶段还是能够投入生产环境。让我们比较一下典型的负载：

差距在数百到数千倍。对于原型开发，这意味着 3M 免费 token 足以进行最初的智能体运行测试。对于每天处理数十万请求的生产环境，节省的资金每月可达数万美元 — 代码依然是 PydanticAI，只需更改 base_url。

一个 jg-xxx 密钥和一个余额既适用于 OpenAI 格式 (/v1)，也适用于 Anthropic 格式 (/v1/messages) — 但对于 PydanticAI，使用上述 OpenAI 兼容端点就足够了。

PydanticAI 的第二个关键能力是工具（tools）。函数可以通过装饰器 @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-your-key",
    ),
)

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。

如何选择模型：MiniMaxAI/MiniMax-M2.7 — 适用于长对话和平衡型任务，输出高达 8192。deepseek-ai/DeepSeek-V4-Flash-0731 — 网络中上下文最长的模型之一 (380K)，且大提示词费用低廉，输出高达 32768。zai-org/GLM-5.3-Flash — 用于复杂推理的推理模型，拥有网络中最长的上下文 (390K)，输出高达 8192；推理会消耗部分 max_tokens，请预留余量（从 600 开始）。这三款模型现在只需一个密钥即可调用，只需更改模型字符串即可。思路相近的工具：用于链式调用和 RAG 的 LangChain，以及用于数据索引的 LlamaIndex。