大模型调用、Token 与上下文

1. 解决什么问题

教材任务把“主题、等级和地区要求”变成语言内容。模型负责候选内容与判断，程序负责数据契约、工具执行和交付条件。首先学会读清一次请求发了什么、收回什么，才能排查所谓“Agent 不工作”。

2. 原理与术语

Token 是模型处理文本的单位，不等同于汉字或单词；输入上下文包括指令、资料、教材及工具描述，输出也占模型支持的预算。上下文窗口是容量上限，增加无关资料并不保证质量。提示词规定任务，但不能授予程序权限。

3. 输入、输出和执行

run_model 接收角色、任务 ID、上下文和目标 Schema。真实模式构造 system/user 消息，调用 /chat/completions；收到工具请求后执行或提交结构化结果。每次工具结果回传都可能再次调用模型，所以一次业务节点不一定只发生一次推理。

数据	作用
SYSTEMS[role]	角色任务与行为边界
context	本轮任务、来源、规则及必要教材
tools	角色可请求的能力与结果提交契约
usage	供应商返回的调用计量，不代表教材质量

4. 容易混淆

模型“记得前一步”通常是应用再次发送了数据，并非 API 自动读取 PostgreSQL。角色上下文隔离也不等于模型权重隔离。本系统不同角色默认使用同一个配置模型，不能据此宣称评审错误彼此独立。

5. 最小示例

下面把上下文与历史对话分开，不调用外部服务：

import json
context = {"request": {"theme": "校园"}, "sources": [], "rules": {}}
message = {"role": "user", "content": json.dumps(context, ensure_ascii=False)}
assert "messages" not in context
print(message)

6. 教材系统的实现

演示模式走 demo_result，使用固定模板并明确写入 synthetic=true；它能验证路由，不能证明文本生成质量。真实模式使用兼容 Chat Completions 的 HTTP 契约，不支持的端点不会自动退回演示。

7. 源码与数据结构

阅读 system/app/providers.py 的 SYSTEMS、run_model、demo_result，再读 graph.py::context。事件 model_call 保存角色、模型、上下文摘要、延迟和 token；密钥由 settings.py 读取，不进入上下文对象。

8. 取舍与替代

生成/评审/修订各限制十轮；素材计划按课文块数计算“三次请求×块数+两轮余量”，且最多218轮；结构修复最多两次；没有实现 tokenizer 预算、自动上下文压缩或流式输出。扩大资料规模前，应增加 token 预算与裁剪策略，而非无限拼接。高层框架可简化调用，但仍需保留错误分类与原始计量。

9. 实验与验收

先按实验约定启动演示系统，在 system 目录执行：

curl -s -H "X-API-Key: ${LAB_API_KEY:-}" -H 'Content-Type: application/json' \
  -d '{"theme":"校园生活","scenario":"normal"}' http://127.0.0.1:8000/api/jobs

在操作台查看该任务事件，比较生成与评审的 role、context_hash；应明确显示演示模式。真实模式需另配凭据后重复实验，记录供应商 usage，不能借用演示耗时作真实指标。

10. 故障排查

401 先查密钥与端点；无工具请求检查模型能力与响应状态；上下文过长先减资料与工具描述。HTTPX 的超时不等同于整个工作流时间预算。日志避免打印授权请求头，错误报告应保留任务和供应商请求标识。

11. 面试题与追问

问：为什么评审还要重新发教材？ 模型无法自动读取业务状态，需要构造本轮上下文。追问：资料越来越多怎么办？ 先按范围召回和去重，再测 token 与正确率；压缩可能丢证据，因此保留来源并设置预算。能说明当前尚未实现自动压缩，比空称“支持长上下文”准确。

再追问：一次节点为什么有多条计费记录？ 工具请求回传会触发下一轮推理，应按实际调用计量。

STAR 应用：假设实验场景，R 为应核对的证据

对应	S：情境	T：目标	A：行动	R：验收证据
主问	评审需重新读取教材	提供充分且隔离的上下文	调用 context 构造教材、规则与来源	检查评审输入包含当前版本，不含生成对话
追问一	资料超过模型容量	控制输入预算	统计输入并优先保留相关证据；本版尚无自动裁剪	记录token与来源覆盖，不能仅看字符数
追问二	同一节点多次推理	解释成本来源	关联工具回传、轮次和usage	核对实际调用次数，不把节点数当调用数

这些是设计讨论的参考表达，实际执行前不能改写为已取得的历史成果。

12. 官方资料与版本

文本生成、Function Calling、HTTPX 超时。核验日期 2026-11-03；本实现采用 Chat Completions 协议，不能直接套用 Responses 字段。实际模型名与兼容能力以配置和在线验证为准。