电商售后复合条件诊断助手

基于 microsoft/graphrag 3.0.4 的可运行项目骨架，Python >=3.11,<3.14。本项目已用该版本实际安装包核对配置、抽取格式、local search API 和增量流程；不声称它是当前最新版本。默认使用 OpenAI 兼容接口，模型、地址和密钥均从 settings.yaml / 环境变量读取。

文件与用途

settings.yaml                          GraphRAG 3.0.4 索引和模型配置
prompts/entity_extraction.txt           五占位符源模板、七类实体、八条关系签名
prompts/entity_extraction.compiled.txt  CLI 实际读取的自定义抽取模板
prompts/summarize_descriptions.txt       保留频次、统计口径和涉及型号
prompts/community_report.txt            按问题—解决方案对组织社区报告
prompts/local_search.txt                只根据证据回答、强制引用 Sources
scripts/preprocess_reviews.py           评论筛选、不可变业务ID、原文和元数据保存
scripts/compile_prompts.py              编译固定分隔符
scripts/build_index.sh                  预处理 → graphrag index → 导出 → 向量索引
scripts/export_graph.py                 原始抽取快照 → 严格类型化图、拒绝记录隔离
scripts/build_vectors.py                文本和锚点向量缓存、余弦检索索引
scripts/incremental_update.py           暂存增量索引、刷新受影响社区、发布和回滚副本
scripts/evaluate.py                     混合/纯向量比较、50条人工关系抽检模板
app/main.py                            FastAPI、实时API路由、文本块查询
app/retrieval.py                        GraphRAG local 适配和混合检索
app/schema.py                          实体、边、答案声明的校验
app/config.py                          共用 GraphRAG 配置的 OpenAI 客户端
app/static/                            中文前端：问答、路径图、证据弹窗、示例演示
scripts/start_frontend.ps1              Windows 启动前后端同一服务
data/sample_reviews.jsonl               虚构评论/工单，非真实商品诊断资料
data/eval_queries.jsonl                 人工标注格式示例，需要按实际抽取名称核对
tests/                                 筛选、真实版本适配、路径、溯源、指标测试
.env.example / pyproject.toml           环境变量和依赖
requirements.lock.txt                  本次 Windows/Python 3.13 验证环境的依赖版本快照

安装和配置

以下命令从项目根目录运行。使用 Python 3.11、3.12 或 3.13；本次开发验证使用 Windows / Python 3.13。

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env

Linux/macOS 激活用 source .venv/bin/activate，复制配置用 cp .env.example .env。如果 PowerShell 阻止激活，可直接使用 .venv\Scripts\python.exe、.venv\Scripts\graphrag.exe。

同为 Windows / Python 3.13 时，可使用 python -m pip install -e ".[dev]" -c requirements.lock.txt 复现本次依赖版本。其他平台/Python版本按 pyproject.toml 解析兼容依赖，不强制套用该平台快照。

编辑 .env，填写聊天和 embedding 密钥；可以是相同密钥，不能保留示例占位值。接口需支持 Chat Completions、JSON object 输出和 Embeddings。不同供应商可以分别设置两个 API base。更换 embedding 模型或维度后需要重建对应向量索引；不要混用新旧向量。

GRAPHRAG_API_KEY=你的聊天密钥
GRAPHRAG_CHAT_MODEL=gpt-4.1-mini
GRAPHRAG_API_BASE=https://api.openai.com/v1
GRAPHRAG_EMBEDDING_API_KEY=你的向量密钥
GRAPHRAG_EMBEDDING_MODEL=text-embedding-3-small
GRAPHRAG_EMBEDDING_API_BASE=https://api.openai.com/v1

不需要运行 graphrag init；它可能覆盖本项目的专用配置和 prompt。

输入和预过滤

输入是 JSONL，一行一条 REVIEW 或 TICKET：

{"id":"R100","kind":"REVIEW","sku":"X1","parent_id":"VAC-X","model":"X1","specs":"电池2500mAh，尘杯0.6L","category":"吸尘器","created_at":"2026-10-01","scenario":"宠物家庭","verified_purchase":true,"helpful_votes":10,"rating":2,"text":"这里填写完整评论原文，中文至少十五个分词后的词。"}

id/text/sku/model/specs 必须提供，kind 默认 REVIEW；REVIEW 还需 verified_purchase/helpful_votes/rating。TICKET 不执行购买验证、星级和长度过滤。未提供的真实规格应填写“未提供”，不要编造。created_at 使用 ISO 日期，供时间过滤。

REVIEW 保留条件严格为：

verified_purchase is true
AND (该批次同SKU有效购买评论 helpful_votes 前40% OR 1 <= rating <= 3)
AND word_count(text) >= 15

排名先在已验证购买记录中计算，取 ceil(0.4*n) 条，并列按业务ID稳定排序，然后执行长度过滤。中文使用 jieba 分词，英文按词边界计数，不按汉字数或空格数冒充词数。布尔字符串 "true" 不等于 JSON 布尔值 true。这些口径写明以便复现实验；如需全平台历史百分位，应在上游统一计算。

预处理保留全文于 data/source_records.json，并生成 input/records.jsonl。只转发商品、场景和日期等允许元数据，不转发输入中的 price/stock 字段。用户原文中的历史价格陈述仍属于原文证据，prompt 禁止将其抽成实时价格库存事实。

同一业务ID的原文及业务元数据视为不可变；增量新增时复用同ID但修改内容会报错。更正或删除资料需全量重建，不能用新的ID掩盖删除旧事实的需要。

构建索引

Git Bash / Linux / macOS：

bash scripts/build_index.sh data/sample_reviews.jsonl

PowerShell 等价步骤：

python -m scripts.compile_prompts
python -m scripts.preprocess_reviews data/sample_reviews.jsonl
graphrag index --root . --dry-run --skip-validation
graphrag index --root . --method standard
python -m scripts.export_graph
python -m scripts.build_vectors

--dry-run --skip-validation 解析配置并跳过模型连通性探测，不执行 LLM 索引。单独 --dry-run 仍会向模型 API 发出验证请求。实际索引与 build_vectors 需要有效 API 配置并会调用模型。预处理输出为 0 或抽取没有合法关系时应检查数据，不把空索引视为成功。

生成的主要产物：

文件	用途
output/entities.parquet 等	原生 GraphRAG local search 数据
output/raw_entities.parquet / raw_relationships.parquet	摘要之前的抽取快照
output/typed_graph.json	校验后的七类实体、方向明确的边和原文块
output/rejected_extractions.json	类型错误、原文不匹配、端点缺失的隔离记录
output/lancedb/	原生 GraphRAG 向量库
output/vectors.npz / vectors.json	混合检索与纯向量基线共用的余弦向量索引
output/embedding_cache.json	按模型/地址/文本内容哈希复用向量

typed_graph.json 是应用侧严格 Schema 的权威图。原生 GraphRAG 会先按 source/target 聚合关系，且标准表没有自定义关系类型列，因此不能只靠 prompt 就假设关系类型已被存储。

本项目使用标准五字段关系元组，将 REL=has_solution; EVIDENCE=逐字证据 写入 description。导出器从 raw 快照的 description/text_unit_ids 对应列表逐条恢复类型、方向和真实块ID，校验端点签名及证据子串；不同类型的同端点关系可以并存。未通过的关系被隔离，不参与混合检索。子串存在只能证明引用真实，是否语义上支持该关系仍须人工评估。

REVIEW/TICKET 节点的 text 始终来自保存的完整原文，source_chunk_id 指向一个真实块，source_chunk_ids 保留跨块全部来源。PRODUCT 描述由原文商品元数据补上型号和关键规格，不依赖模型能否记全。

3.0.4 适配说明

• v3.0.4 使用 completion_models、embedding_models、chunking、input_storage、output_storage，不是 v2 的 models/chunks/input.base_dir。
• 抽取器只 .format(entity_types=..., input_text=...)，分隔符固定为 <|>、##、<|COMPLETE|>。因此源文件保留需求规定的五个占位符，编译器仅替换三种分隔符；settings.yaml 指向随项目提供的 compiled 专用模板。修改源模板后先重新编译。
• text_units.parquet 在 v3 使用单值 document_id，不是 v2 的 document_ids 列表。
• 需求列出的“8种关系”实际是 8条允许签名、7个不同关系名称，因为 REVIEW 和 TICKET 共用 reports_symptom。程序严格采用该列表。
• 不给 TICKET 增添 mentions_product，也不给 PRODUCT 增添 reports_symptom。TICKET 与 SKU 的联系通过源文档元数据筛选；没有合法评论边时，不伪造完整 Product→Ticket 图路径。

版本依据为实际安装的 3.0.4 发布包，相关上游入口为 GraphRAG 源码、CLI 文档、Local Search 文档。在线主分支文档可能对应更新版本，升级前需重新验证这些适配测试。

启动和查询

已经包含可视化前端 「循证 · 售后诊断工作台」，由同一个 FastAPI 服务提供，不需要 Node.js、npm 或单独的前端编译。

python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

打开 http://127.0.0.1:8000/ 使用前端；http://127.0.0.1:8000/docs 保留接口调试。Windows 也可在项目根目录执行 powershell -File scripts/start_frontend.ps1，指定其他端口用 -Port 8001。服务运行期间保持终端开启，按 Ctrl+C 停止。

前端支持：

• 输入诊断问题，在混合检索和局部检索之间切换；支持 Ctrl/⌘ + Enter 提交。
• 筛选商品品类、日期、图遍历跳数和召回数量。
• 展示诊断结论与逐条证据引用；图中箭头保留真实关系方向，节点可通过鼠标或键盘选择并高亮对应证据。
• 点击证据卡片读取 /chunks/{id}，展示完整原文、型号、场景和日期；纯文本证据不会被伪造成图路径。
• 复制结论，导出包含查询、答案和 provenance 的 JSON；导出示例时明确包含 demo: true。
• 显示等待、取消等待、超时、服务错误、无证据和实时 API 提示。取消只停止浏览器等待，服务端任务可能继续。
• 桌面双栏与手机单栏布局；窄屏图谱在卡片内横向滚动，不挤宽整个页面。

没有密钥和索引时，点击 “示例演示” 即可体验完整界面。示例仅在浏览器内运行，不请求 LLM，所有商品、评论、工单和处理指引均为虚构，并有持续可见的提示。点击“开始诊断”才会调用真实后端，不会悄悄用示例替代真实检索结果。

API 懒加载索引，/health 能在无索引时使用；新增 index_ready 表示三个应用索引文件是否存在，不代表内容校验或模型连通性已通过。此骨架面向本地开发，服务没有用户鉴权或租户隔离。前端使用同源相对 API 路径，不暴露密钥，也不依赖远程字体或图标 CDN。

$body = @{query="X1 在宠物家庭的滤网堵塞问题有什么解决方案？"; top_k=5; hops=3} | ConvertTo-Json
Invoke-RestMethod http://127.0.0.1:8000/search/hybrid -Method Post -ContentType "application/json; charset=utf-8" -Body ([Text.Encoding]::UTF8.GetBytes($body))

端点行为：

• POST /search/local 调用真实的 graphrag.api.local_search，用于单跳事实；仅把实际答案引用的 Sources 映射为真实块ID。无可核验引用则返回证据不足。
• POST /search/hybrid 先向量召回 PRODUCT/PARENT_PRODUCT/SYMPTOM 和原始文本，再在校验后的图上扩展 1–3 跳；展开优先级为 reports_symptom > has_solution > co_occurs_with > has_component，另外保留必要结构边和评论边。
• 含“为什么/导致/关联/共同/哪些型号也/解决方案/怎么处理”的请求会路由到 hybrid，至少2跳，默认3跳。含“多少钱/有没有货/价格/库存/参数是什么”等时优先返回“请调用商品服务实时 API”的占位响应，provenance 为空；不会调用模型猜测实时数据。
• 可提交 category、since、until；时间和品类条件在向量候选筛选与每条扩展边上生效。local 请求带此类过滤会转 hybrid，因为原生 local 不支持该元数据谓词。过去三个月使用 Asia/Shanghai 日历月计算，显式日期优先。
• GET /chunks/{source_chunk_id} 返回原始索引块和源记录元数据；未知ID返回404。

“这款/同一品类”的指代不能从无上下文的 query 自动解析，请传具体型号和 category。自由文本场景（如宠物家庭）由向量和证据生成匹配；未实现任意自然语言条件的可靠解析器。

合法完整路径示例（返回 JSON 的简化形式）：

{
  "path": ["PRODUCT:X1", "mentions_product", "REVIEW:R1", "reports_symptom", "SYMPTOM:滤网堵塞", "has_solution", "SOLUTION:清洗滤网"],
  "directions": ["reverse", "forward", "forward"],
  "source_chunk_id": "真实text_units.id",
  "evidence_text": "原文中的一至两句直接证据",
  "source": "graph_path",
  "url": "/chunks/真实text_units.id"
}

PRODUCT→REVIEW 是反向遍历真实的 REVIEW→PRODUCT，关系类型本身没有反转。每条路径还带 edges，每条边分别记录自己的来源块；多块证据会产生多个 provenance 项，不能把整条链错误归因于一个块。纯文本召回 source=text_chunk、path=[]，不伪造成图证据。

同一条诊断路径要求边的 SKU 范围一致，防止共享症状把不同型号的处理方式错误串联。跨型号查询可以返回多条不同 SKU 的路径；统一处理方式需要分别有原文支持。

生成模型只允许引用本次提供的 evidence_id、实体和关系；应用拒绝不存在的证据ID。自然语言仍可能误述，严格引用和类型校验不等同于答案事实完全正确。原生 local 的自由文本输出尤其需要人工质量检查。

日常增量与每月重建

日常只抽取新文档，用原生 graphrag update 做实体名称消歧和合并；本项目再仅刷新包含受影响实体的社区报告。每月全量重建一次，校准社区划分漂移。这里提供更新命令与策略，没有自动创建定时任务。

3.0.4 已支持稳定的 update 命令，因此没有伪造 incremental: true，也无需启用名称+向量相似度 upsert 临时方案。update_output_storage 是真实支持的配置项。原生实体消歧是按规范化名称合并，不是自动理解近义词；SKU/父商品/业务ID 的确定性命名有助于避免错误合并，症状别名需要上游词表或人工治理。

停止 API 服务后执行：

python -m scripts.incremental_update --input data/new_reviews.jsonl
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

更新步骤：

1. 对新增批次预过滤并追加到累计 input；已存在的 title 不再抽取。当前版本仅处理新增，不自动删除或覆盖旧文档。
2. 将当前索引复制至 update_output/<run>/output 暂存区，在那里执行真实的 graphrag update，当前已发布索引保持不变。
3. 从本次 delta 的 raw 快照导出类型化边，按实体规范名称合并，保留全部旧原文块和证据；不把旧快照当成本次新图重复导入。
4. 原生流程先为新社区生成报告并保留旧报告；本项目额外找出成员包含变动实体的社区，只对这些社区重新生成报告。报告上下文纳入当前成员的最新关联边，社区划分保持原生增量结果。
5. 复用未变文本的缓存向量，验证新的类型化图与向量索引，再发布；旧索引保存在本次运行目录的 published_previous。Windows 文件夹交换存在短暂空档，因此需要停止服务，并在发布后重启以清除内存快照。

原生 update 会重走部分 embedding 流程，不能保证所有原生向量计算只覆盖新增对象；应用自己的 embedding cache 按内容复用。受影响社区过大超过 max_input_length 时更新会停止，保留现有索引；可调整预算或执行月度重建。

增量刷新后的报告用于本项目 local search。额外刷新报告之后，原生 community_full_content 向量尚未再次同步；本项目没有开放 global search。如未来增加 global search，需要同步报告向量。月度全量索引会重建全部报告及向量。

更新失败时暂存区保留用于排查。若失败发生在发布前，继续使用原索引；发布过程改名失败会尝试恢复旧目录。回滚时停服，将当前 output 另行备份，再把对应 published_previous 恢复为 output。不要并发执行全量构建、增量构建或服务发布。

月度重建使用完整历史原始数据重新预过滤、执行上述全量构建命令；先备份原 output。这是必要的周期性校准，不能将原生增量合并误称为全图重新聚类。

评估

先将示例查询集替换为人工确认的真实查询、关键节点及有向边三元组。示例解法名称是参考标签，LLM 可能使用不同但等价名称，应固定词表或人工对齐；不要为了让系统得分好而事后删除漏召回标签。

# 创建固定随机种子的最多50条关系抽检表；不覆盖已有人工标注
python -m scripts.evaluate --sample-relations
# 人工逐条阅读 source_text，将 supported 填 true/false，并记录 reviewer_note
# 使用同一查询集、embedding、top_k及答案模型比较两种检索（会调用API）
python -m scripts.evaluate --run
# 已有预测时离线重算指标
python -m scripts.evaluate --predictions data/predictions.jsonl

输出 data/evaluation_report.json：

指标	口径
path_coverage	每条人工链的关键节点+有向边被有效 provenance 覆盖的比例，再按查询平均
complete_chain_rate	标注链的全部关键节点和边均已覆盖的查询比例
relation_precision	人工判定原文直接支持的关系数 / 已标注关系数；至少50条才标记 complete
provenance_clickable_rate	source_chunk_id 能解析到真实原文块的比例
verbatim_evidence_rate	引用文本确实是对应原文块连续子串的比例
schema_hallucination_rate	答案结构化声明/路径/显式类型记号包含非法类型或关系的答案比例

原文子串校验不会自动填人工关系标签；少于50条、未标注或没有分母均明确报告不足或 null，不伪造精确率。可点击率通过与 /chunks 共用的块映射校验，不代表测量了网络可用率。缺失或失败的查询按路径未覆盖处理，另报 errors_or_missing。

纯向量基线完全禁用图锚点和遍历，仅使用相同原始文本向量召回。它不产生结构化图路径，因此严格路径覆盖率通常为0；此指标不能单独证明其自然语言答案更差，需结合人工答案正确性检查。

“Schema 幻觉率”是需求指定的狭义指标，不能识别所有中文自然语言事实捏造或因果误判。生产评估还需人工检查措辞、型号适用范围和方案有效性。示例数据不足以做50条关系的有意义抽样；需要真实标注集后才可报告模型质量。

验证与限制

python -m pytest -q
python -c "import pathlib,py_compile; [py_compile.compile(str(p),doraise=True) for folder in ('app','scripts','tests') for p in pathlib.Path(folder).rglob('*.py')]"
graphrag index --root . --dry-run --skip-validation

测试使用模拟模型响应和小型 Parquet 固件检查实际版本的格式及接口，不调用付费 LLM。运行测试不需要真实密钥。没有配置真实模型时，仅能验证代码、配置和适配，不能声称真实语料索引或线上答案质量已验收。

本次交付验证：28项测试通过，19个Python文件通过 py_compile，真实3.0.4 CLI离线配置解析通过。前端两个 JavaScript 模块通过 node --check；已在浏览器验证示例诊断、图节点与证据联动、原文弹窗、日期校验、实时 API 路由、未配置模型时的错误提示，以及手机宽度下无页面横向溢出。示例预过滤为5条输入保留3条。测试环境有一条 Starlette/httpx 弃用提示，不影响断言通过；尚未进行真实模型的全量/增量索引或50条关系人工精确率验收。

已知边界：向量检索采用内存精确余弦，适合骨架/小规模数据；大规模应替换为带元数据过滤的向量库。最多3跳无法从父商品穿过变体、评论、症状再到方案（共4跳），可能依赖同时召回的具体商品/症状锚点。图扩展有候选数上限，可能漏召回；症状频次要按独立业务记录去重，prompt 明确禁止把块数当评论数，但尚未提供通用频次统计 API。价格库存服务仅有路由占位，尚未连接真实电商平台。