baibaiAIGC如何调用大模型API?OpenAI兼容客户端的设计、重试与输出校验机制
baibaiAIGC如何调用大模型API?OpenAI兼容客户端的设计、重试与输出校验机制
baibaiAIGC 是一款面向论文与长文档的多轮改写工具,通过调用大模型 API 逐段消除文本的"AI 味"。它的核心是一个轻量级 OpenAI 兼容客户端:不依赖任何第三方 SDK,直接用 Python 标准库发起请求,并配合"可重试错误分类 + 输出校验"两道防线,保证长文档逐块改写时稳定可靠。这篇文章带你用大白话看懂这条调用链路。
一、先认识 baibaiAIGC:API 调用发生在哪一层?
baibaiAIGC 支持 4 种使用方式,只有其中两种会真正"主动"调用外部大模型 API:
| 模式 | 是否调用外部 API | 说明 |
|---|---|---|
| 对话 skill 模式 | ❌ 由宿主对话模型代劳 | 不需要配置 API Key |
| 脚本 API 模式 | ✅ 逐块调用 | 入口 scripts/run_aigc_round.py |
| Web 模式 | ✅ 逐块调用 | 浏览器里配置、测试、执行 |
| App 桌面版 | ✅ 逐块调用 | 基于 Tauri 的桌面应用 |
四种模式的完整介绍见 README.md 与 references/usage.md。
无论走哪条入口,真正"发出 HTTP 请求"的代码都收敛在同一个文件:scripts/llm_client.py。这种"单一出口"的设计意味着:换模型服务商时,你只需要改一行 base_url,其他逻辑完全不动。
二、客户端设计:零 SDK、双接口自适应
1. 只用标准库发请求
打开 llm_client.py 可以看到,整个客户端只 import 了 json、os、urllib——没有 openai、httpx、requests。好处很直接:
- 依赖极少,
pip install一步到位,不会和别的库打架; - 行为完全可预期,方便排查"到底发了什么、收到了什么"。
2. 自动识别两种 OpenAI 兼容接口
OpenAI 生态目前有两类常见接口,baibaiAIGC 都支持:
chat/completions:经典的messages对话式接口(默认);responses:较新的 Responses 接口,请求体用input字段。
识别逻辑在 normalize_api_type 中,规则非常聪明:
- 你显式传了
api_type(chat_completions或responses),以它为准; - 没传?就看
base_url是否以/responses结尾,是则自动切到 responses 模式; - 都不满足,默认按
chat/completions处理。
随后 build_endpoint 负责把 base_url 拼成完整端点(已带 /chat/completions 就不会重复拼接),build_payload 则按接口类型生成不同的请求体:chat 模式包装成 messages: [{role: "user", content: ...}],responses 模式直接传 input 字符串。
3. 请求头里的"隐形"细节
build_headers 会在你提供的 api_key 前拼上 Bearer 前缀放入 Authorization 头,同时带上固定的 Content-Type: application/json 等默认头。这意味着你只需要提供原始的 API Key,格式由客户端负责兜底。
三、模型配置从哪来?三条通道、一个归宿
在脚本模式下,read_api_config 按"命令行参数 → 项目专属环境变量 → 通用 OpenAI 环境变量"的顺序解析配置:
| 配置项 | 优先变量 | 兜底变量 |
|---|---|---|
| API Key | BAIBAIAIGC_API_KEY |
OPENAI_API_KEY |
| 模型名 | BAIBAIAIGC_MODEL |
— |
| 接口地址 | BAIBAIAIGC_BASE_URL |
OPENAI_BASE_URL |
| 接口类型 | BAIBAIAIGC_API_TYPE |
按 base_url 自动推断 |
兜底到 OPENAI_API_KEY / OPENAI_BASE_URL 是个贴心设计:如果你机器上已经为 OpenAI 配过环境变量,baibaiAIGC 可以"零配置"直接工作;同时它优先读自己专属的变量,避免多项目互相串号。
Web / App 模式则把同样的四要素(baseUrl、apiKey、model、apiType,外加 temperature)存进本地配置文件,默认值定义在 scripts/app_config.py 中,前端"模型配置"卡片上填什么,这里就校验并归一化什么。
💡 配好后不必盲跑——test_llm_connection 会用一条 ping 短消息(temperature 设为 0、超时仅 20 秒)发起真实请求,Web 页面的"测试连接"按钮走的就是它,能提前暴露 90% 的配置问题。
四、重试与容错:先判断"值不值得重试"
大模型 API 是外部依赖,网络抖动、限流、服务端 5xx 都是常态。baibaiAIGC 的容错思路不是"无脑重试",而是给每个错误打上 retriable 标签,再让上层决定动作。
所有请求异常都被统一包装成 LLMClientError,分类规则如下:
| 故障场景 | 错误码 | 可重试? |
|---|---|---|
| HTTP 5xx / 429 限流 | provider_http_error |
✅ 是(源码) |
| 其他 4xx(如 Key 错误) | provider_http_error |
❌ 否,重试也没用 |
| 网络不通 / 超时 | provider_network_error |
✅ 是 |
| 返回非 JSON / JSON 损坏 | provider_non_json_response、provider_invalid_json |
✅ 是 |
| JSON 结构不符合预期 | provider_unexpected_schema |
❌ 否,属于接口不兼容 |
这个设计很务实:401 这种错误重试一百次也是 401,直接快速失败;而 429 限流和瞬时网络错误,等一等再试往往就通了。
失败一个块 ≠ 整轮作废
长文档会被切成多个块逐块调用模型(最多 3 块并发)。当某个块调用失败时,run_round 会抛出 RoundPausedError 并触发三件事:
- 把失败信息写进
last_error/last_error_chunk_id; - 已完成的块输出保存在进度文件(
*_progress.json)里; - 下一轮再启动时跳过已完成的块,从断点继续。
也就是说,哪怕 200 个块跑到第 150 个时网络断了,前 149 个块的成果也不会白费——这是长文档批处理场景里非常关键的"断点续跑"能力。
五、输出校验:拦截模型"过度热情"的闲聊
调大模型改写论文,最坑的失败不是报错,而是模型不报错但答非所问——比如开头加一句"修改后:"、结尾补一句"如果你愿意,我也可以继续帮你"。这种"回答式包装"混进正文,会让改写结果直接报废。
baibaiAIGC 的解法是在 validate_chunk_output 中做四道硬校验:
- 空输出:模型返回空内容,直接拒绝;
- 回答式前缀/后缀:扫描输出开头 80 字符与结尾 120 字符,命中"说明:"、"修改后:"、"改写后:"、"如果你愿意"、"我也可以继续帮你"等特征词即拒绝(模式表)。同时做了"原文继承"豁免——如果原文开头本来就有"说明:",就不会误伤;
- 擅自加格式:输出里新出现
**、##、- **等 markdown 标记而原文没有,拒绝; - 长度异常膨胀:输出超过原文 2 倍或超出 200 字符,判定为"回答式跑偏",拒绝。
校验没过的块不会直接失败,而是进入 一次自动重发:在 prompt 里追加一份 RETRY_OUTPUT_CONTRACT,明确告诉模型"上次你用了解答式口吻,这次直接给正文"。这套"校验 + 带约束重试"的组合拳,相关边界用例都在 tests/test_aigc_round_service.py 中有覆盖。
六、实战速查:三步接上你自己的模型
🔑 第 1 步:提供三要素(以脚本模式为例)
$env:BAIBAIAIGC_API_KEY="your_api_key"
$env:BAIBAIAIGC_MODEL="your_model"
$env:BAIBAIAIGC_BASE_URL="https://your-endpoint/v1"
也可以改用 --api-key、--model、--base-url 命令行参数(见 run_aigc_round.py)。
第 2 步:测试连接 在 Web 页面点"测试连接",或先用短文本试跑一轮,确认端点、Key、模型名三者都能对上。
第 3 步:执行改写
python scripts/run_aigc_round.py origin/论文.txt 1 origin/论文.txt finish/intermediate/论文_round1.txt finish/intermediate/论文_round1_manifest.json --chunk-limit 850
如果暂时不想连模型,加 --dry-run 可以只做切块与 prompt 拼接校验,输出和输入一致,适合先验证流程。
七、小结
- 客户端设计:标准库实现、零 SDK,
chat_completions/responses双接口按 URL 自适应,换服务商只改base_url; - 配置解析:项目专属变量优先、OpenAI 通用变量兜底,CLI / 环境变量 / Web 面板三通道统一归一化;
- 重试容错:用
retriable标签区分"值得重试"与"快速失败",块级断点续跑保住长文档进度; - 输出校验:空输出、回答式包装、乱加格式、长度膨胀四道闸门,不合规自动带约束重试一次。
想继续深挖,可以从这几个入口入手:
- 核心客户端:scripts/llm_client.py
- 轮次服务与输出校验:scripts/aigc_round_service.py
- 脚本入口:scripts/run_aigc_round.py
- Web 后端接入:scripts/app_service.py
- 使用说明:references/usage.md