summary-generation.md 11 KB
五类场景摘要生成
2026-09-24 青浦区介绍与新闻（F117）
用户授权后，仅对新增998条通用知识按article场景调用现有DeepSeek配置生成摘要。初轮8条返回格式不符合单字段JSON约束，定向重试后5条成功，余3条采用更明确的单字段要求成功；最终998条均为generated/stop，output/checks/f117-news-summary.py --verify独立复验通过。原有3233条增强记录保持一致；完整原文及链接仍单独保存，摘要不代表新闻所述政策当前有效。增量报告为prepared/f117_summary_report.json。
2026-09-24 惠企政策更新（F116）
用户授权后，仅对新导出的170条惠企政策调用现有DeepSeek配置生成摘要，全部generated/stop并独立复验；其余3063条增强知识逐字节沿用旧快照。增量脚本为output/checks/f116-policy-summary.py，加--verify只读复验；结果记录prepared/f116_summary_report.json。摘要输入仍仅含结构化政策事实，“涉及原文”完整进入知识记录供后续原文核验，不作为本轮摘要请求正文。全量摘要入口的旧缓存可能大量不命中，不能等同于仅更新政策。摘要未经逐条人工语义和有效性评审。
2026-09-22 企业服务中心知识更新（F107）
新增reference/企业服务中心介绍和联系方式.json中的4条知识，按general/article处理；现有3242条知识及增强摘要逐字段保留，总计3246条。正文、电话、地址、图片链接、原文链接及更新时间保留在完整记录中；不将服务介绍认定为政策卡片或已核验有效资料。
本轮使用本地增量操作脚本output/checks/f107-summary.py复用现有摘要函数，仅处理新增4条；加--verify只读核对缓存和输出。当前增量摘要证据为knowledge/prepared/f107_summary_report.json，旧summary_report和local_refresh_report为历史快照。全量摘要入口会按当前配置重新匹配缓存，不能视为必然只处理新增条目。
F081授权更新：用户已授权新增53条公安Excel通过配置的DeepSeek生成LLM摘要。使用python -m src.step1_knowledge_prepare.refresh_local --llm-workbook生成及--llm-workbook --verify独立校验，当前报告仍为local_refresh_report.json，method为llm-workbook-preserve-existing-v1。只处理工作簿，原3189条摘要逐字段保留；沿用原摘要提示、预算、重试及SQLite缓存，全部成功才更新增强文件。默认本地刷新和普通摘要入口拒绝覆盖已存在的工作簿LLM摘要，避免降级为本地抽取。首次未授权的工作簿仍可使用本地抽取；本次明确授权已记录，无需重复确认。
脚本：src/step1_knowledge_prepare/summarize.py。使用 .env 中的 DeepSeek 配置和 summary_input.py 中的五套场景提示词，每条人工分段对应一次独立请求，保持全文，不截断、不再次切分。
使用方式
在仓库根目录运行：
# 仅本地检查配置、路由、token预算，不调用 API
.\.venv\Scripts\python.exe -m src.step1_knowledge_prepare.summarize --dry-run
# 为各场景抽取一条尚未生成的记录，真实调用 API（可选）
.\.venv\Scripts\python.exe -m src.step1_knowledge_prepare.summarize --sample-per-scenario 1
# 全量生成；已有匹配缓存自动复用，失败项重试
.\.venv\Scripts\python.exe -m src.step1_knowledge_prepare.summarize
# 对照原知识、当前提示词/配置和缓存校验增强结果，不调用 API
.\.venv\Scripts\python.exe -m src.step1_knowledge_prepare.summarize --verify-only
默认读取四个原始 prepared/{policy,finance,general,qa}.jsonl，不递归读取新生成文件；更换目录可用 --prepared，更换配置文件用 --env-file，tokenizer 用 --tokenizer。
五类路由
部署全量更新入口：python -m src.step1_knowledge_prepare.summarize --llm-workbook，显式允许Excel记录同其他知识一起使用已配置的远程模型摘要，适用于新机器及混合来源变更；配合相同参数加 --verify-only 核验。该选项不能和 --local-only 同用。普通入口继续保留Excel本地抽取与禁止降级已有LLM摘要的保护；旧 refresh_local --llm-workbook 增量入口仍保留。完整部署流程见部署说明。
| 场景 | 来源判断 | 摘要侧重点 |
|---|---|---|
| policy | 惠企政策 | 事项、对象、支持、条件、收益与时间 |
| finance | 金融产品 | 融资需求、准入与条款，利率未标注周期时不补写年化 |
| service_guide | general 中办事指南集合，或具有基本信息和受理条件的结构 | 材料、流程、时限、方式，保留材料备注中的按情形限制 |
| service_catalog | general 中六大服务板块集合，或具有类别和服务说明的结构 | 服务内容、对象、支持标准、材料、步骤及部门 |
| article | general 中其余政策、法规、文章 | 主题、对象、规定、措施、限制与例外 |
QA 不调用 LLM，retrieval_text 直接使用 data.question；目录明确排除。原先四类存储结构不变，增加的五类场景只是摘要提示词路由。
当前提示词版本 summary-v3-five-scenarios。事实来源与原字段保留规则详见 summary_input.py；惠企政策中的模型建议与 source_annotations 不进入摘要输入。
环境配置
所有LLM请求显式使用 temperature=0（F055），包括本阶段摘要和在线问答。摘要缓存指纹包含请求参数，因此新温度不会命中旧温度的缓存；既有生成文件不会自动重写。
DEEPSEEK_API_KEY、DEEPSEEK_BASE_URL、DEEPSEEK_MODEL 沿用用户已有值。密钥仅在内存中用于对应 HTTPS 请求头，不输出、不写缓存或文档，不跟随 HTTP 重定向。
进程环境变量优先于 .env。支持普通赋值、单/双引号及行尾注释，不展开变量或执行 .env 内容。
| 变量 | 本轮初始值 | 含义 |
|---|---|---|
| SUMMARY_CONTEXT_TOKENS | 32768 | 本地总输入输出预算，不是服务端模型上限 |
| SUMMARY_MAX_OUTPUT_TOKENS | 4096 | 首次请求的 API max_tokens，限制输出 |
| SUMMARY_TOKEN_MARGIN | 512 | 估计输入与服务端包装的余量 |
| SUMMARY_MAX_OUTPUT_LIMIT | 32768 | 翻倍重试的输出预算上限 |
| SUMMARY_MAX_CONTEXT_LIMIT | 131072 | 翻倍重试的本地总预算上限 |
| SUMMARY_MAX_ATTEMPTS | 3 | 单条每次运行最多请求次数，包含首次，支持1–5 |
| SUMMARY_CONCURRENCY | 8 | 并发请求数量，支持1–32 |
| SUMMARY_TIMEOUT_SECONDS | 120 | 单次网络超时秒数 |
默认非思考模式 thinking.type=disabled，JSON Output 模式，temperature=0.2。输出为 {"summary":"摘要正文"}。
参考 DeepSeek Chat Completions：max_tokens 是输出上限；finish_reason=length 表示生成受到长度限制。模型的服务器上下文能力不能通过修改本地总预算改变。
完整性与翻倍重试
必须同时满足以下条件才标记 generated：finish_reason=stop、返回内容能解析为 JSON 对象、仅包含 summary 字符串且非空。 即使 JSON 恰好完整，只要 finish_reason=length 也不会作为成功结果；不保存截断正文作为摘要。
- 遇到 length：下次输出上限翻倍（默认4096→8192→16384），如实际/估计输入＋新输出＋余量超过当前总预算，则将总预算也翻倍，直到能容纳。
- 达到最大次数或配置的扩容上限：标记 failed，保留错误码及逐次预算、结束原因和用量，可调整
.env后续跑。 - JSON 损坏、空摘要、网络超时、429及服务端5xx：有限次数退避重试；没有明确 length 证据时不把所有格式错误都当成 token 不足。
- 认证等不可重试 HTTP 错误：该条直接失败，不泄漏服务端错误正文。应先用抽样命令确认服务配置再全量运行。
- 本地首次预算不够时预检失败，不截断输入、不发出该批请求；提高
.env预算后重跑。
结构完整并不等于语义准确。摘要保留 review_status=not_reviewed，不能作为政策有效性或用户业务评审通过的证据。
输出及断点恢复
新知识位于同一 prepared 目录，原文件保持不变：
- policy.with_summary.jsonl
- finance.with_summary.jsonl
- general.with_summary.jsonl
- qa.with_summary.jsonl
- summary_report.json：覆盖数量、状态、错误、成功记录用量和输入/输出哈希。
每条原知识所有字段均保留，另增：
| 字段 | 含义 |
|---|---|
| summary_result | 解析后的 JSON 对象 {"summary":"..."}；无摘要时 null |
| summary | 摘要正文，方便检索读取 |
| summary_status | generated / failed / pending / not_required_qa / excluded_catalog |
| retrieval_text | 标题＋摘要；QA只使用原问题；失败、未生成与目录不提供检索文本 |
| summary_metadata | 场景、提示词版本、请求/事实哈希、模型、UTC时间、实际用量、结束原因、有效预算和 attempt_history |
SQLite 缓存 .summary_cache.sqlite3 每条完成即提交；.summary.lock 使用操作系统文件锁，进程退出自动释放，防止多个生成任务并行写同一目录。
输入、提示词版本/内容、模型、端点或生成预算变更会改变缓存键，不会复用旧摘要；密钥不参与缓存键。
请求中断时已提交的缓存保留；重跑只生成缺失或失败项。少数响应已在服务端完成但本地尚未提交的请求可能重发。
生成结束才导出完整增强 JSONL，每个文件临时替换，报告最后写入；整批不提供事务保证，中断后需重跑并执行 verify-only。
抽样模式会输出包含 pending 的全量记录，报告 complete=false，不能直接当作完整摘要库。全量模式存在失败会返回非零。
用量汇总是当前成功记录的最终响应用量，不包含旧版本样例、被中断且未提交请求等全部账单成本；重试详情见 attempt_history。
prepared 的真实内容及缓存已被 Git 忽略。代码、提示词和说明可版本管理，本轮不进行 Embedding 或 Milvus 入库。
本轮运行结果（2026-09-10）
- 完成2,248条摘要：policy183、finance185、article244、service_guide1,578、service_catalog58；QA928条原问题用于索引，目录1条排除，3,177条原知识全部保留。
- 全部成功结果通过 JSON schema 和 finish_reason=stop 检查；全量 verify-only 通过，重复生成 scheduled=0，未新增请求。原知识与 reference 复验通过。
- 当前并发为用户最终指定的8；曾按加速请求短暂调为32，随后恢复8并从缓存继续。
- 有32条发生过重试并最终成功，没有 finish_reason=length；本批未实际触发token翻倍，翻倍逻辑由合成回归覆盖。最高最终输出905 token。
- 最终成功响应用量：输入4,538,813、输出805,989 token；本批输入比离线估计每条多24 token，已被512余量覆盖。这不是包含旧提示词样例和中断请求的完整账单。
- 五场景已进行样例抽查；所有记录仍标为not_reviewed，不宣称政策效力或逐条业务语义已人工审核。