panda

面向“大熊猫知识”场景的知识图谱工程：从 Markdown 抽取结构化知识，写入 Neo4j，再基于图谱做问答。

当前能力

• 文档抽取：tools/panda_history_extractor.py
  • 单文件/目录批量抽取
  • 失败重试与断点续跑
  • 支持“问题清单驱动”的二次定向抽取（补强细节事实）
  • 运行结果独立目录输出
  • 支持语料栏目：熊猫知识 / 熊猫谣言 / 熊猫资料（入库时写入 r.category）
• 图谱写入：tools/neo4j_graph_writer.py
  • 支持 Neo4j Aura
  • 关系类型使用抽取结果中的 predicate
  • 节点/关系保存 evidence、source_file、topic、category
• 图谱问答：tools/neo4j_qa.py
  • 两阶段检索（先文档候选，再关系精排）
  • 可先选栏目再提问，按 r.category 缩小检索范围
  • 展示流程模块化：运行信息 -> Cypher 解析 -> 命中节点关系 -> 回答 -> 来源
  • 支持 persona（如 kid）
  • 支持来源文档展示、交互模式与问答 JSON 自动落盘
  • 当知识库无证据时自动触发 LLM 通用知识兜底回答（会标注为非知识库证据）
  • 回答质量评分支持规则护栏（拒答/无依据不再出现高分）

环境准备

1. Python 3.10+
2. 安装依赖：
   • pip install -r requirements.txt
3. 配置 .env（示例）：

QWEN_APIKEY=your_qwen_api_key
NEO4J_URI=neo4j+s://xxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_password
NEO4J_DATABASE=neo4j

常用命令

1) 按栏目抽取文档

熊猫知识：

python -m tools.panda_history_extractor --docs-dir "docs/熊猫知识" --category "熊猫知识" --max-concurrency 5 --retry-failed-times 1

熊猫谣言（建议用辟谣汇总，避免把谣言标题当事实）：

python -m tools.panda_history_extractor --docs-dir "docs/熊猫谣言" --category "熊猫谣言" --max-concurrency 5

熊猫资料（个体档案等）：

python -m tools.panda_history_extractor --docs-dir "docs/熊猫资料" --category "熊猫资料" --max-concurrency 3

--category 可省略：会按路径自动推断（docs/熊猫谣言、docs/谣言与辟谣 → 熊猫谣言；docs/熊猫资料 → 熊猫资料；其余默认熊猫知识）。

基于细节问题清单做“基础抽取 + 二次定向抽取”：

python -m tools.panda_history_extractor --docs-dir "docs/熊猫知识" --category "熊猫知识" --focus-questions-json "docs/panda_detailed_questions.json" --max-concurrency 5

2) 抽取单文件

python -m tools.panda_history_extractor --md-path "docs/熊猫知识/【熊猫知识】气味标记 - 成都大熊猫繁育研究基地.md" --category "熊猫知识"

3) 写入 Neo4j

建议全量重载时先清空，再分别写入各栏目结果；只更新某一栏目时用 --clear-category：

python -m tools.neo4j_graph_writer --result-json "data/wiki/<knowledge_run>/<result>.json" --clear
python -m tools.neo4j_graph_writer --result-json "data/wiki/<rumor_run>/<result>.json"
python -m tools.neo4j_graph_writer --result-json "data/wiki/<profile_run>/<result>.json"
# 仅替换资料栏目：
# python -m tools.neo4j_graph_writer --result-json "..." --clear-category "熊猫资料"

4) 问答（单问，指定栏目）

python -m tools.neo4j_qa --category "熊猫知识" --question "大熊猫是怎么交流的" --persona kid --show-sources
python -m tools.neo4j_qa --category "熊猫谣言" --question "大熊猫是猫科动物吗" --show-sources
python -m tools.neo4j_qa --category "熊猫资料" --question "和花是什么时候出生的" --show-sources

说明：

• neo4j_qa 每次结果会附带 quality 字段（0-100 分与等级）。
• 若知识库未命中证据，会自动走 llm_fallback 给出通用知识回答，并在答案中提示该回答非知识库证据。

5) 问答（交互）

python -m tools.neo4j_qa --interactive --persona educator --show-sources

进入后会先选择栏目；也可随时用 :category 熊猫知识|熊猫谣言|熊猫资料|全部 切换。

交互问答默认自动保存每轮 JSON 到 sandbox/qa_sessions/（可指定会话名）：

python -m tools.neo4j_qa --interactive --show-sources --session-name panda_demo

如需关闭自动保存：

python -m tools.neo4j_qa --interactive --no-save-json

6) 导出 Neo4j schema 统计到 JSON

默认输出到 sandbox/neo4j_schema_<timestamp>.json：

python scripts/inspect_neo4j_schema.py --database 941568f4

指定输出文件：

python scripts/inspect_neo4j_schema.py --database 941568f4 --output "sandbox/neo4j_schema_latest.json"

7) 评估知识库问答效果（准确率/命中率）

先准备 JSONL 评测集（每行一个问题）：

{"id":"q1","question":"大熊猫幼仔一般在哪里出生？","gold_answer":"一般出生在母兽搭建的产仔巢（树洞或岩洞）中。","gold_sources":["【熊猫知识】繁殖 - 成都大熊猫繁育研究基地.md"]}

运行评测：

python -m tools.qa_evaluator --dataset "data/eval/qa_eval.jsonl" --qa-top-k 20 --hit-at-k 5 --output "reports/qa_eval_latest.json"

可选：启用 LLM 语义裁判（速度慢且有调用成本）：

python -m tools.qa_evaluator --dataset "data/eval/qa_eval.jsonl" --use-llm-judge

说明：qa_evaluator 会复用 neo4j_qa 的在线质量字段（如 online_quality），便于离线评测与在线表现对齐。

目录说明

• docs/熊猫知识/：知识源文档（栏目：熊猫知识）
• docs/熊猫谣言/：辟谣文档（栏目：熊猫谣言）
• docs/熊猫资料/：个体档案等资料（栏目：熊猫资料）
• docs/谣言与辟谣/：谣言与辟谣原始/衍生文档
• tools/：抽取、入库、问答工具
• scripts/：辅助脚本（如 Neo4j schema 统计导出）
• data/wiki/：抽取运行结果目录（按运行批次分组）
• config/model.yaml：模型配置（问答默认走 text_generation）

注意事项

• 若 Aura 连接报认证错误，先检查 NEO4J_URI/USERNAME/PASSWORD/DATABASE。
• 若要重跑某批次，优先使用 --resume-run-output-dir 续跑。
• 生产数据谨慎使用 neo4j_graph_writer --clear。
• 只更新某一栏目时，优先使用 --clear-category <栏目名>，避免误清其他栏目。
• 重新全量入库时，建议先 --clear 再写入，避免旧关系缺少 category。