常用接入术语

接入架构

接入优势

• DSPy Signature 把任务的输入和输出写成字段，调用方可以直接读取结构化属性。
• Predict、ChainOfThought 和 ReAct 等模块可以复用同一签名，切换策略时不必重写业务字段。
• dspy.LM 支持 OpenAI 兼容 Chat Completions 服务，可显式设置 api_*ase、密钥和生成参数。
• 程序可以使用标注样本和指标做离线评估；只有基线稳定后才适合引入优化器。
• KingFlow 控制台集中管理模型、密钥和用量，便于隔离不同环境。

开始前的准备

• 准备 Python 3.10 或更高版本，并安装 uv。
• 在 KingFlow AI 控制台创建以 sk- 开头的 API Key，确认余额和模型分组可用。
• 复制目标模型的完整模型 ID，并确认上下文窗口满足待处理文档长度。
• 准备少量脱敏测试文本，首次联调不要直接加载生产知识库。
• 确认运行环境可以访问 api.**nju**shen.com。

创建 DSPy 测试项目

uv init dspy-kingflow-demo
cd dspy-kingflow-demo
uv add dspy 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": "只回复 DSPY_READY"}],
    "stream": false
  }'

配置环境变量

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

.env
.venv/
__pycache__/
artifacts/

编写结构化预测示例

import os

import dspy
from dotenv import load_dotenv

load_dotenv()

model = f'openai/{os.environ["KINGFLOW_MODEL"]}'
lm = dspy.LM(
    model,
    api_*ase=os.environ["KINGFLOW_*ASE_**L"],
    api_key=os.environ["KINGFLOW_API_KEY"],
    temperature=0.2,
    **x_tokens=800,
)
dspy.configure(lm=lm)

print(lm("只回复 DSPY_CONNECTED")[0])

class ReleaseChecklist(dspy.Signature):
    """根据系统信息生成上线检查结果；信息不足时列入风险。"""

    system_info: str = dspy.InputField(desc="待检查的部署信息")
    checks: list[str] = dspy.OutputField(desc="可执行的上线检查项")
    risks: list[str] = dspy.OutputField(desc="仍需处理的风险")
    verdict: str = dspy.OutputField(desc="只能是 pass 或 review")

check_release = dspy.Predict(ReleaseChecklist)
result = check_release(
    system_info=(
        "API Key 已放入 Secret；已设置月度额度；"
        "尚未配置 429 重试；日志不记录请求正文。"
    )
)

print(result.checks)
print(result.risks)
print(result.verdict)

切换执行策略

reasoning_check = dspy.ChainOfThought(ReleaseChecklist)
result = reasoning_check(
    system_info="密钥已隔离；额度已设置；故障告警尚未配置。"
)
print(result.checks)
print(result.risks)
print(result.verdict)

运行和验证

uv run python **in.py

1. 先执行 KingFlow 基础请求，确认返回 DSPY_READY。
2. 创建 .env 和 .gitignore，再将完整示例保存为 **in.py。
3. 运行程序，确认直接调用返回 DSPY_CONNECTED。
4. 检查 Predict 是否返回 checks、risks 和 verdict 三个字段。
5. 在 KingFlow 控制台核对模型、密钥、调用次数和 Token 用量。

正式环境配置

• 先固定模型、温度和测试集，记录基线准确率、延迟和 Token 用量，再比较模块或提示变化。
• 类型化输出仍需业务校验；列表可能为空，枚举值也要在应用层再次验证。
• 优化器会产生额外模型调用和费用，先用小样本试跑并设置预算上限。
• 开发、测试和生产使用独立 LM 配置、密钥和额度，避免评估流量进入生产账单。
• 为 429 和 503 设置有限退避重试，并同时限制并发、请求时长和 Token 预算。
• 记录查询 ID、文档版本、模型、状态码、耗时和用量，但不要记录完整密钥和敏感原文。

文档与密钥安全

• 只在 .env、密钥管理器或部署平台 Secret 中保存 API Key，并定期轮换。
• 把输入样本和模型输出视为不可信数据，进入日志或评估集前完成脱敏。
• 训练集、开发集和测试集分开管理，避免同一示例同时用于优化和验收。
• 保存优化后的程序或演示样本时检查敏感字段，禁止把真实密钥写入 artifact。
• 为开发、测试和生产设置独立密钥、额度和告警，异常用量出现后立即停用旧密钥。

上线检查清单

• 基础接口已经返回 DSPY_READY。
• KINGFLOW_*ASE_**L 为 https://api.**nju**shen.com/v1。
• KINGFLOW_MODEL 使用控制台中的完整模型 ID。
• dspy.LM 已设置 api_*ase、模型 ID 和生成参数。
• .env 已被 .gitignore 排除，仓库中没有明文密钥。
• Signature 的输入、输出和字段描述已经明确。
• Predict 已返回 checks、risks 和 verdict。
• KingFlow 控制台的模型、密钥和用量符合预期。

常见故障排查