常用接入术语

接入架构

接入优势

• Py**ntic 模型把预期字段写进代码，业务逻辑可以直接使用经过校验的 Python 对象。
• OpenAIProvider 支持自定义 *ase **L 和 API Key，适合连接 OpenAI 兼容**。
• OpenAIChatModel 明确使用 Chat Completions，能够避开只兼容该接口时的路径差异。
• 请求上限可以阻止工具或校验流程持续循环，便于控制调用次数和成本。
• KingFlow 控制台集中管理模型、密钥和用量，便于区分开发、测试与生产环境。

开始前的准备

• 准备 Python 3.10 或更高版本，并安装 uv。
• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，确认余额和模型分组可用。
• 复制目标模型的完整模型 ID，并确认该模型支持所需的结构化输出或工具调用能力。
• 准备独立测试目录，首次联调不要发送生产数据或启用高权限工具。
• 确认运行环境可以访问 api.**nju**shen.com。

创建 Py**ntic AI 测试项目

uv init py**ntic-ai-kingflow-demo
cd py**ntic-ai-kingflow-demo
uv add py**ntic-ai python-dotenv

验证 KingFlow 基础接口

curl https://api.**nju**shen.com/v1/chat/completions \
  -H "Authorization: *earer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<KingFlow控制台中的完整模型ID>",
    "messages": [{"role": "user", "content": "只回复 PYDANTIC_READY"}],
    "stream": false
  }'

配置环境变量

KINGFLOW_*ASE_**L=https://api.**nju**shen.com/v1
KINGFLOW_API_KEY=sk-你的密钥
KINGFLOW_MODEL=<KingFlow控制台中的完整模型ID>

.env
.venv/
__pycache__/

编写结构化输出智能体

import os
from dotenv import load_dotenv
from py**ntic import *aseModel, Field
from py**ntic_ai import Agent, UsageLimits
from py**ntic_ai.models.openai import OpenAIChatModel
from py**ntic_ai.providers.openai import OpenAIProvider

load_dotenv()

class DeploymentCheck(*aseModel):
    sum**ry: str = Field(description="总体判断")
    risks: list[str] = Field(description="需要处理的风险")
    steps: list[str] = Field(description="按顺序执行的步骤")

provider = OpenAIProvider(
    *ase_url=os.environ["KINGFLOW_*ASE_**L"],
    api_key=os.environ["KINGFLOW_API_KEY"],
)

model = OpenAIChatModel(
    os.environ["KINGFLOW_MODEL"],
    provider=provider,
)

agent = Agent(
    model,
    output_type=DeploymentCheck,
    instructions=(
        "你是 API 上线审核助手。只根据用户提供的信息判断，"
        "风险和步骤必须具体、**证。"
    ),
)

result = agent.run_sync(
    "为新的 API 接入生成上线前检查结果。",
    usage_limits=UsageLimits(request_limit=5),
)

print(result.output.model_dump_json(indent=2))

先验证纯文本模式

plain_agent = Agent(model, instructions="用简洁中文回答")
result = plain_agent.run_sync(
    "列出 API 接入上线前的三个检查项。",
    usage_limits=UsageLimits(request_limit=3),
)
print(result.output)

运行和验证

uv run python **in.py

1. 先执行 KingFlow 基础请求，确认返回 PYDANTIC_READY。
2. 创建 .env 和 .gitignore，再将完整示例保存为 **in.py。
3. 运行程序，确认结果包含 sum**ry、risks 和 steps 三个字段。
4. 故意把字段类型改错进行一次测试，确认 Py**ntic 能发现不符合要求的输出。
5. 在 KingFlow 控制台核对模型、密钥、调用次数和 Token 用量。

正式环境配置

• 固定使用 OpenAIChatModel；只有端点明确支持 Responses API 时才改用 OpenAIResponsesModel。
• 把 Provider 和模型构造集中到单独模块，开发、测试和生产环境使用不同密钥。
• 字段描述应说明含义、格式和允许范围；关键数值可以增加 Py**ntic 范围约束。
• 为每次运行设置 request_limit，并同时控制超时、并发、Token 和业务预算。
• 工具默认只读并采用白名单；涉及写入、支付、删除或外发时增加人工审批。
• 记录状态码、模型、耗时、请求次数和 Token 用量，但不要记录完整密钥或敏感输入。

密钥与工具安全

• 只在 .env、密钥管理器或部署平台 Secret 中保存 API Key，并定期轮换。
• 发送给模型前做数据最小化和脱敏，不把无关客户资料放入提示词。
• 模型生成的结构化对象通过了类型校验，但业务规则仍需单独验证。
• 工具参数经过 Py**ntic 校验后仍要检查权限、资源归属和操作范围。
• 为开发、测试和生产设置独立额度及告警，异常用量出现后立即停用旧密钥。

上线检查清单

• 基础接口已经返回 PYDANTIC_READY。
• KINGFLOW_*ASE_**L 为 https://api.**nju**shen.com/v1。
• KINGFLOW_MODEL 使用控制台中的完整模型 ID。
• OpenAIChatModel 和 OpenAIProvider 已连接 Chat Completions 兼容端点。
• .env 已被 .gitignore 排除，仓库中没有明文密钥。
• 结构化结果能够通过 DeploymentCheck 校验。
• 单次运行设置了请求上限，工具采用白名单与最小权限。
• KingFlow 控制台的模型、密钥和用量符合预期。

常见故障排查