企业官网建设流程全解析

如何修改提示词或模型后用 docsgpt-cli bench 对 DocsGPT Agent 做回归验证

【免费下载链接】DocsGPTPrivate AI platform for agents, assistants and enterprise search. Built-in Agent Builder, Deep research, Document analysis, Multi-model support, and API connectivity for agents.项目地址: https://gitcode.com/GitHub_Trending/do/DocsGPT

在 DocsGPT 里改完 Agent 的提示词、或者把 Agent 背后的模型换掉之后，最直接的问题是：答案质量有没有变差？DocsGPT 官方文档给出的做法是从终端跑可复现的基准检查——独立 CLI 项目 docsgpt-cli 提供的bench命令。它把一个目录里的基准用例逐一发给你的 Agent，并对返回的答案做断言，文档称之为改动提示词、更换模型或重新摄取来源之后的快速 "is everything still good?" 检查，对 DocsGPT Cloud 和自托管部署都适用。

前提条件

• 一个运行中的 DocsGPT 部署（Cloud 或自托管均可）。
• docsgpt-cli。本仓库文档明确说明它是独立于 DocsGPT 服务端的 CLI 项目，包含bench命令；架构文档中它被描述为 client 和可选的 remote device host。
• 一个 Agent 及其 API key。在 web 应用中进入 Settings -> Agents -> Create New 即可创建带 API key 的 Agent（每个 Agent 自动附带一个 key），也可以调用/api/create_agent端点创建，详见 API Keys 指南。

先完成变更：改提示词或换模型

回归验证本身不产生变更，它验证的是"变更之后 Agent 是否仍按预期回答"。所以下文先交代两种变更各自的入口，再回到 bench 的操作。

修改提示词

在 web 应用中按SideBar -> Settings -> Active Prompt找到当前提示词，点编辑图标即可修改（见 Customizing Prompts）。修改前需要知道两种模式的差别：

• 纯文本提示词（不含{{ }}）被当作 persona，放进标准提示词的## Your role区块，内置的回答规则、安全边界等仍然保留；
• 一旦包含{{ }}模板语法，DocsGPT 按原样渲染且不再追加任何内容，安全边界需要你自己写进提示词。

更换模型

• Cloud 版：在聊天界面点击当前选中的 LLM，从下拉列表中改选其他模型（见 How to use different LLM）。
• 自托管：修改.env文件，关键是LLM_PROVIDER（如openai）、LLM_NAME、OPENAI_BASE_URL和API_KEY；模型注册表在服务启动时扫描环境变量自动注册可用模型，LLM_NAME匹配到已注册模型时成为默认模型（见 Local Inference）。

变更生效后，用同一套基准用例重新跑一遍，就是本文的核心操作。

建立基准套件

docsgpt-cli 的bench命令运行一个用例目录，并可用init脚手架生成：

docsgpt-cli bench # run the suite in ./bench docsgpt-cli bench ./my-suite # or any directory docsgpt-cli bench init my-suite # scaffold a new suite

套件是一个目录，包含可选的bench.yaml（全局默认值）和每个用例一个目录，目录内放case.yaml和附件文件：

bench/ bench.yaml 01-basic-answer/ case.yaml 02-with-attachment/ case.yaml report.pdf

bench.yaml中的关键字段（以下为官方文档示例）：

agent: my-agent # key name from `docsgpt-cli keys`, or a literal API key target: v1 # v1 | stream | webhook # base_url: https://gptcloud.arc53.com # judge: # agent: judge-agent # agent used for LLM-as-judge grading concurrency: 2 timeout: 120s # repeat: 3 # run each case N times… # min_pass: 2 # …and require at least this many passes

agent填docsgpt-cli keys中的 key 名称（每台机器本地解析）或直接填字面 API key；base_url指向你的部署地址。case.yaml定义问题与断言，官方示例（数值是文档示例，问题与期望值需替换成你自己的业务场景）：

description: "Support agent quotes the refund window" tags: [smoke, support] question: "How many days do customers have to request a refund?" expect: answer: contains: ["30 days"] # case-insensitive substrings not_contains: ["I don't know"] regex: ['\b30\s*days?\b'] sources: { min: 1 } # retrieval sources returned repeat: 3 # tolerate LLM flakiness min_pass: 2

expect的每个小节都是可选的，省略的小节就不检查：answer支持contains/not_contains/regex，json可把答案当 JSON 解析后按字段断言，tools断言 Agent 必须/禁止调用的工具，judge用配置的 judge Agent 做 LLM-as-judge 评分，limits限制耗时与 token 用量，golden对比录制快照。用例中的repeat/min_pass用来容忍 LLM 输出的偶发不稳定。

跑基线，再在变更后重跑对比

第一次运行（也就是提示词/模型变更之前）直接跑套件：

docsgpt-cli bench

每次运行都会保存在~/.docsgpt/bench/<suite>/下，这是后续基线对比的依据。变更提示词或模型后，用--baseline last重跑同一套件：

docsgpt-cli bench --baseline last

该命令会把本次运行与上一次运行做 diff，标出回归（pass → fail）、修复（fail → pass）以及延迟/token 漂移。加--verbose可以打印具体答案和 judge 的评分理由，便于定位是哪一个用例出了问题。

判读标准就是文档给出的退出码：0全部用例通过，1存在失败，2配置错误。退出码为 1 且--baseline last标出了 pass → fail 的用例，说明这次提示词或模型变更引入了回归。

如果你正在多个提示词版本之间迭代，文档给出的最快方式是对比两个 Agent：

docsgpt-cli bench --key prompt-v1 --vs prompt-v2

套件会分别对两个 Agent 各跑一遍并输出并排对比，prompt-v1/prompt-v2是docsgpt-cli keys中的 key 名称。

如果只想跑部分用例，可以用名称过滤或按 tag 过滤：

docsgpt-cli bench -k refund # filter by name/description docsgpt-cli bench --tags smoke # filter by tags docsgpt-cli bench --repeat 3 --concurrency 4

可选：录制 golden 快照与接入 CI

Golden 快照：docsgpt-cli bench record运行用例并把每个答案保存到用例目录的golden.json；之后在用例中设置expect: {golden: true}，后续运行就会与该快照对比，--update可刷新快照。适合答案应当高度稳定（如固定格式输出）的场景。

CI：--json输出机器可读结果，--junit输出 JUnit XML 供 CI 测试报告使用：

docsgpt-cli bench --json > run.json docsgpt-cli bench --junit report.xml

官方文档给出的 GitHub Actions 片段（--key接受~/.docsgpt/config.json中的 key 名称或字面 API key，因此 CI 可直接传密钥）：

- name: Agent benchmarks # --key accepts a key name from ~/.docsgpt/config.json or a literal API key, # so CI can pass the secret directly. run: docsgpt-cli bench --key "$DOCSGPT_API_KEY" --junit bench.xml env: DOCSGPT_API_KEY: ${{ secrets.DOCSGPT_API_KEY }} DOCSGPT_NO_UPDATE_CHECK: "1"

密钥管理与目标协议的边界

bench.yaml和case.yaml中的任何值都可以用${VAR}引用环境变量，使套件可以安全提交到仓库而密钥留在环境里：

agent: ${DOCSGPT_BENCH_KEY} webhook_url: ${DOCSGPT_WEBHOOK_URL} judge: agent: ${DOCSGPT_JUDGE_KEY}

解析顺序：shell 环境变量，然后是套件目录下的.env，再是./.env（简单KEY=value格式的 dotenv 文件，建议加入 gitignore）。变量未设置时加载会直接以清晰错误失败，而不是用空 key 跑基准；只有带花括号的${VAR}形式会被展开，$$转义字面美元符号，YAML 注释行永不展开。不想改 YAML 时，--key和--webhook-url标志也能传入字面密钥与 webhook 令牌。

三个目标协议的能力边界不同，选错会影响断言是否可用：

webhook 目标是异步的：CLI 把{"question": "..."}发到 Agent 的 webhook URL 后轮询任务直至完成；需要审批的工具在 webhook 运行中会被自动拒绝，附件也不支持。另外limits.max_total_tokens只在v1目标下生效，写断言时注意目标与协议要匹配。

完整字段参考见 Benchmarking Agents。回归判断的闭环是：变更 ->docsgpt-cli bench --baseline last-> 退出码为 0 且 diff 中无 pass → fail 即通过；出现失败时用--verbose看具体答案与 judge 理由，再决定回滚还是继续调整提示词。

【免费下载链接】DocsGPTPrivate AI platform for agents, assistants and enterprise search. Built-in Agent Builder, Deep research, Document analysis, Multi-model support, and API connectivity for agents.项目地址: https://gitcode.com/GitHub_Trending/do/DocsGPT