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

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

安装：

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

最简单的例子——通过 Gonka 的代理。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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    provider=OpenAIProvider(
        base_url="https://gate.joingonka.ai/v1",
        api_key="jg-你的密钥",
    ),
)

agent = Agent(model)

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

就是这样——您的 PydanticAI 代理通过 Gonka 去中心化网络以极低的成本运行。run_sync 方法适用于脚本；对于异步代码，有 await agent.run(...)。

模型参数：Qwen3-235B 的上下文窗口为 128K 令牌（131072），通过 Gateway 的最大输出长度为 8192 令牌。可以通过模型设置限制输出（OpenAIChatModelSettings(max_tokens=8192)）。还提供 moonshotai/Kimi-K2.6（最多 3072 输出令牌）和 MiniMaxAI/MiniMax-M2.7（最多 4096）——只需在 OpenAIChatModel 的第一个参数中更改模型名称即可。

选择 PydanticAI 的主要原因是结构化输出。您不是通过正则表达式解析响应文本，而是将结果描述为 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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(
    "提取数据：Anna 是后端开发人员，精通 Python、Go 和 Postgres"
)
print(result.output)
# name='Anna' role='后端开发人员' skills=['Python', 'Go', 'Postgres']
print(result.output.skills)  # ['Python', 'Go', 'Postgres'] — 已经是 list[str]，不是文本

这之所以有效，是因为 Qwen3-235B（以及其他两个 Gonka 模型）支持原生 tool calling——PydanticAI 依赖它来返回有效的 JSON 结构。您最终得到的是类型化的 Python 对象，而不是需要手动解析的字符串。这对于数据提取、分类、表单填充和 RAG 管道来说非常理想，因为结果需要以严格的格式向下传递到代码中。

PydanticAI 是一个用于代理和管道的框架，这些代理和管道持续运行：提取数据、调用工具、处理请求流。在这里，令牌成本决定了一个项目是停留在原型阶段还是进入生产。我们比较一下典型的工作负载：

差异高达数百甚至数千倍。对于原型来说，这意味着 10M 免费令牌足以进行数百次代理运行。对于每天处理数十万个请求的生产环境，每月可节省数万美元——使用相同的 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(
    "Qwen/Qwen3-235B-A22B-Instruct-2507-FP8",
    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.00001 美元，而 OpenAI/Anthropic 则为 0.04–0.22 美元。

选择哪个模型：Qwen/Qwen3-235B-A22B-Instruct-2507-FP8 —— 默认模型，质量平衡最佳且输出限制最大（8192）。moonshotai/Kimi-K2.6 擅长编码和复杂推理（输出最多 3072）。MiniMaxAI/MiniMax-M2.7 —— 适用于长对话（输出最多 4096）。所有这三种模型均可通过一个密钥直接使用——只需更改模型字符串即可。类似理念的工具：LangChain 用于链和 RAG，LlamaIndex 用于数据索引。