{
"canonical_name": "OSU-NLP-Group/HippoRAG",
"compilation_id": "pack_6a596163d04a4fa6b891ac2fc6b1a33d",
"created_at": "2026-05-16T23:17:59.685415+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=skill, recipe, host_instruction, eval, preflight",
"recommended_asset_types=skill, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install hipporag` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install hipporag",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_6af1d129112249d0a86308ea13635357"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_710c0bc71c880d8f61ce1c4869284076",
"canonical_name": "OSU-NLP-Group/HippoRAG",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/OSU-NLP-Group/HippoRAG",
"slug": "hipporag",
"source_packet_id": "phit_816c0ba1957c4ad6ad8eeb69f819558f",
"source_validation_id": "dval_b637e1ee2e31488884f3c56dfa70fcd5"
},
"merchandising": {
"best_for": "需要信息检索与知识管理能力，并使用 chatgpt的用户",
"github_forks": 358,
"github_stars": 3520,
"one_liner_en": "HippoRAG 2: From RAG to Memory
",
"one_liner_zh": "HippoRAG 2: From RAG to Memory
",
"primary_category": {
"category_id": "research-knowledge",
"confidence": "high",
"name_en": "Research & Knowledge",
"name_zh": "信息检索与知识管理",
"reason": "strong category phrase match from project identity and outcome"
},
"target_user": "使用 chatgpt 等宿主 AI 的用户",
"title_en": "HippoRAG",
"title_zh": "HippoRAG 能力包",
"visible_tags": [
{
"label_en": "Knowledge Retrieval",
"label_zh": "知识检索",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-knowledge-retrieval",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Structured Extraction",
"label_zh": "结构化提取",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-structured-extraction",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_816c0ba1957c4ad6ad8eeb69f819558f",
"page_model": {
"artifacts": {
"artifact_slug": "hipporag",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install hipporag",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/OSU-NLP-Group/HippoRAG#readme",
"verified": true
}
],
"display_tags": [
"知识检索",
"知识库问答",
"结构化提取",
"节点式流程编排",
"评测体系"
],
"eyebrow": "信息检索与知识管理",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要信息检索与知识管理能力，并使用 chatgpt的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "HippoRAG 2: From RAG to Memory
"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "chatgpt",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "skill, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：add_fact_edges function adds the same edge twice?",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_6c7ca8232561460290f1ad50663233af | https://github.com/OSU-NLP-Group/HippoRAG/issues/174 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：add_fact_edges function adds the same edge twice?",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：pypi hipporag libraries",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_0da5afa434114138a3c745efba4c9ded | https://github.com/OSU-NLP-Group/HippoRAG/issues/168 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：pypi hipporag libraries",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an extremely long time. Is this normal?",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_90b68b1be49048efba510bfd10623d41 | https://github.com/OSU-NLP-Group/HippoRAG/issues/173 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an…",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OpenAI version incompatibility in latest 2.0.0a4 version",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f6679eb5cf884eb9a2d003b39da93c8d | https://github.com/OSU-NLP-Group/HippoRAG/issues/140 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：OpenAI version incompatibility in latest 2.0.0a4 version",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows Compatibility Issues with vLLM dependency",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_57d57b9365f342db9a5e8ed48727e99e | https://github.com/OSU-NLP-Group/HippoRAG/issues/117 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Windows Compatibility Issues with vLLM dependency",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：How to use local embedding_model_",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_dd0e2350e55240b3ab754359ca93cb11 | https://github.com/OSU-NLP-Group/HippoRAG/issues/127 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：How to use local embedding_model_",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_b735fa4a09f942db8f1825092ef8e368 | https://github.com/OSU-NLP-Group/HippoRAG/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to distinguish Hipporag1 from Hipporag2",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_7dc27422dd8b4cb8a1384848ddbfa750 | https://github.com/OSU-NLP-Group/HippoRAG/issues/167 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：How to distinguish Hipporag1 from Hipporag2",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Inquiry on Sample Selection for HippoRAG Experiments",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_6a0069bfedfc4cf28e0cc18e51171a42 | https://github.com/OSU-NLP-Group/HippoRAG/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Inquiry on Sample Selection for HippoRAG Experiments",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Quadratic runtime during indexing",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_2681acee71064f72b24098fba0e05227 | https://github.com/OSU-NLP-Group/HippoRAG/issues/170 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Quadratic runtime during indexing",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_b65aca3d12234444b97a67bb7baac278 | https://github.com/OSU-NLP-Group/HippoRAG/issues/178 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：division by zero",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_49e401ba15b74b5d943336fa0a2dceda | https://github.com/OSU-NLP-Group/HippoRAG/issues/93 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：division by zero",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 18 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：add_fact_edges function adds the same edge twice?。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 14,
"forks": 358,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 3520
},
"source_url": "https://github.com/OSU-NLP-Group/HippoRAG",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "HippoRAG 2: From RAG to Memory
",
"title": "HippoRAG 能力包",
"trial_prompt": "# HippoRAG - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 HippoRAG 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: HippoRAG 2: From RAG to Memory
输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. p1：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. p2：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. p3：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. p4：知识图谱构建。围绕“知识图谱构建”模拟一次用户任务，不展示安装或运行结果。\n5. p5：LLM模型集成。围绕“LLM模型集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p1\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p2\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p3\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p4\n输入：用户提供的“知识图谱构建”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p5\n输入：用户提供的“LLM模型集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p1：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / p2：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / p3：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / p4：Step 4 必须围绕“知识图谱构建”形成一个小中间产物，并等待用户确认。\n- Step 5 / p5：Step 5 必须围绕“LLM模型集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/OSU-NLP-Group/HippoRAG\n- https://github.com/OSU-NLP-Group/HippoRAG#readme\n- README.md\n- src/hipporag/HippoRAG.py\n- requirements.txt\n- demo_openai.py\n- demo_local.py\n- src/hipporag/StandardRAG.py\n- src/hipporag/embedding_store.py\n- src/hipporag/utils/config_utils.py\n- src/hipporag/llm/base.py\n- src/hipporag/llm/openai_gpt.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 HippoRAG 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: [Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?（https://github.com/OSU-NLP-Group/HippoRAG/issues/178）；github/github_issue: Inquiry Regarding OpenIE Extraction Results for HippoRAG 2（https://github.com/OSU-NLP-Group/HippoRAG/issues/177）；github/github_issue: How to use local embedding_model_（https://github.com/OSU-NLP-Group/HippoRAG/issues/127）；github/github_issue: add_fact_edges function adds the same edge twice?（https://github.com/OSU-NLP-Group/HippoRAG/issues/174）；github/github_issue: Quadratic runtime during indexing（https://github.com/OSU-NLP-Group/HippoRAG/issues/170）；github/github_issue: Take the \"musique\" dataset as an example. The process of constructing an（https://github.com/OSU-NLP-Group/HippoRAG/issues/173）；github/github_issue: Windows Compatibility Issues with vLLM dependency（https://github.com/OSU-NLP-Group/HippoRAG/issues/117）；github/github_issue: OpenAI version incompatibility in latest 2.0.0a4 version（https://github.com/OSU-NLP-Group/HippoRAG/issues/140）；github/github_issue: division by zero（https://github.com/OSU-NLP-Group/HippoRAG/issues/93）；github/github_issue: Inquiry on Sample Selection for HippoRAG Experiments（https://github.com/OSU-NLP-Group/HippoRAG/issues/125）；github/github_issue: How to distinguish Hipporag1 from Hipporag2（https://github.com/OSU-NLP-Group/HippoRAG/issues/167）；github/github_issue: pypi hipporag libraries（https://github.com/OSU-NLP-Group/HippoRAG/issues/168）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/178"
},
{
"kind": "github_issue",
"source": "github",
"title": "Inquiry Regarding OpenIE Extraction Results for HippoRAG 2",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/177"
},
{
"kind": "github_issue",
"source": "github",
"title": "How to use local embedding_model_",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/127"
},
{
"kind": "github_issue",
"source": "github",
"title": "add_fact_edges function adds the same edge twice?",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/174"
},
{
"kind": "github_issue",
"source": "github",
"title": "Quadratic runtime during indexing",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/170"
},
{
"kind": "github_issue",
"source": "github",
"title": "Take the \"musique\" dataset as an example. The process of constructing an",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/173"
},
{
"kind": "github_issue",
"source": "github",
"title": "Windows Compatibility Issues with vLLM dependency",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/117"
},
{
"kind": "github_issue",
"source": "github",
"title": "OpenAI version incompatibility in latest 2.0.0a4 version",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/140"
},
{
"kind": "github_issue",
"source": "github",
"title": "division by zero",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/93"
},
{
"kind": "github_issue",
"source": "github",
"title": "Inquiry on Sample Selection for HippoRAG Experiments",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/125"
},
{
"kind": "github_issue",
"source": "github",
"title": "How to distinguish Hipporag1 from Hipporag2",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/167"
},
{
"kind": "github_issue",
"source": "github",
"title": "pypi hipporag libraries",
"url": "https://github.com/OSU-NLP-Group/HippoRAG/issues/168"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "信息检索与知识管理",
"desc": "HippoRAG 2: From RAG to Memory
",
"effort": "安装已验证",
"forks": 358,
"icon": "search",
"name": "HippoRAG 能力包",
"risk": "可发布",
"slug": "hipporag",
"stars": 3520,
"tags": [
"知识检索",
"知识库问答",
"结构化提取",
"节点式流程编排",
"评测体系"
],
"thumb": "blue",
"type": "Skill Pack"
},
"manual": {
"markdown": "# https://github.com/OSU-NLP-Group/HippoRAG 项目说明书\n\n生成时间：2026-05-16 23:14:33 UTC\n\n## 目录\n\n- [项目介绍](#p1)\n- [快速入门指南](#p2)\n- [系统架构设计](#p3)\n- [知识图谱构建](#p4)\n- [LLM模型集成](#p5)\n- [Embedding模型集成](#p6)\n- [OpenIE信息抽取](#p7)\n- [Prompt模板管理](#p8)\n- [实验复现指南](#p9)\n- [评估与测试](#p10)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速入门指南](#p2), [系统架构设计](#p3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [CONTRIBUTING.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/CONTRIBUTING.md)\n- [requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n \n\n# 项目介绍\n\n## 1 项目概述\n\nHippoRAG（海马体RAG）是一个受神经生物学启发的强大图结构RAG框架，能够使大型语言模型（LLM）识别并利用新知识中的关联信息，从而改进检索效果。资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n当前版本为 **HippoRAG 2**，该版本实现了从传统RAG到记忆系统的跨越，引入非参数持续学习（Non-Parametric Continual Learning）能力。资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md#L1)\n\n### 1.1 项目版本信息\n\n| 属性 | 值 |\n|------|-----|\n| 包名称 | hipporag |\n| 当前版本 | 2.0.0-alpha.4 |\n| Python版本要求 | >=3.10 |\n| 许可证 | 开源 |\n| 官方仓库 | https://github.com/OSU-NLP-Group/HippoRAG |\n\n资料来源：[setup.py:1-12](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L1-L12)\n\n## 2 项目背景与动机\n\n### 2.1 传统RAG的局限性\n\n传统检索增强生成（RAG）系统在处理需要跨段落关联推理的问题时存在明显不足。当用户查询需要关联多个分散的知识片段时，传统方法往往难以有效整合相关信息。\n\n### 2.2 HippoRAG的解决方案\n\nHippoRAG从人类海马体的记忆机制中汲取灵感，构建了一个能够模拟人类长期记忆关联特性的图结构知识库。该系统能够：\n\n- 在新知识中识别和利用关联信息\n- 改进跨段落的事实检索能力\n- 支持多跳推理和关联问答\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 3 系统架构\n\n### 3.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph 输入层\n A[文档输入] --> B[OpenIE信息抽取]\n B --> C[知识图谱构建]\n end\n \n subgraph 处理层\n C --> D[嵌入模型编码]\n D --> E[向量索引]\n end\n \n subgraph 检索层\n E --> F[Personalized PageRank检索]\n F --> G[关联节点链接]\n end\n \n subgraph 问答层\n G --> H[LLM问答]\n H --> I[答案输出]\n end\n```\n\n### 3.2 核心模块说明\n\nHippoRAG项目采用模块化设计，核心代码位于`src/hipporag`目录下。资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n| 模块目录 | 功能描述 |\n|---------|---------|\n| `embedding_model/` | 各类嵌入模型的实现 |\n| `evaluation/` | 评估指标实现 |\n| `information_extraction/` | 信息抽取模型实现 |\n| `llm/` | 大语言模型推理类 |\n| `passage/` | 文档处理相关 |\n| `graph/` | 图结构相关 |\n| `retrieval/` | 检索相关 |\n| `config/` | 配置管理 |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 4 核心功能特性\n\n### 4.1 支持的模型类型\n\nHippoRAG支持多种LLM和嵌入模型部署方式：资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n| 模型类型 | 支持方式 | 示例 |\n|---------|---------|------|\n| OpenAI模型 | API调用 | GPT-4o-mini |\n| OpenAI兼容嵌入 | API调用 + 自定义端点 | NVIDIA NV-Embed-v2 |\n| 本地vLLM部署 | 自托管推理 | Llama-3.1-8B-Instruct |\n| Azure OpenAI | Azure云部署 | gpt-4o-mini |\n\n### 4.2 支持的嵌入模型\n\n- **NV-Embed-v2**：NVIDIA开发的嵌入模型\n- **GritLM**：专门用于检索的嵌入模型\n- **Contriever**：基于对比学习的检索模型\n- **OpenAI兼容模型**：支持自定义嵌入端点\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### 4.3 知识图谱构建\n\n系统支持构建多种类型的知识图谱：\n\n```mermaid\ngraph LR\n A[事实节点] --> B[相似段落节点]\n B --> C[单向/双向关联]\n A --> C\n```\n\n**图结构类型**：\n- `facts_and_sim_passage_node_unidirectional`：事实节点与相似段落节点单向关联\n- 支持自定义图结构类型\n\n资料来源：[main.py:1-15](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py#L1-L15)\n\n## 5 关键配置参数\n\n### 5.1 索引构建参数\n\n| 参数名 | 默认值 | 说明 |\n|--------|--------|------|\n| `openie_mode` | - | OpenIE模式（OpenAI/Transformers-offline/vllm） |\n| `information_extraction_model_name` | - | 信息抽取模型名称 |\n| `synonymy_edge_topk` | 2047 | 构建同义词边时的KNN检索参数 |\n| `synonymy_edge_sim_threshold` | 0.8 | 同义词边相似度阈值 |\n| `is_directed_graph` | False | 是否为有向图 |\n\n资料来源：[src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n### 5.2 检索参数\n\n| 参数名 | 默认值 | 说明 |\n|--------|--------|------|\n| `linking_top_k` | 5 | 每次检索步骤链接的节点数 |\n| `retrieval_top_k` | 200 | 每次步骤检索的文档数 |\n| `damping` | 0.5 | PPR算法的阻尼因子 |\n\n资料来源：[src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n### 5.3 问答参数\n\n| 参数名 | 默认值 | 说明 |\n|--------|--------|------|\n| `max_qa_steps` | 1 | 单个问题的最大推理步骤数 |\n| `qa_top_k` | 5 | 输入给QA模型的顶部K个文档 |\n\n资料来源：[src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n## 6 依赖环境\n\n### 6.1 核心依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| torch | 2.5.1 | 深度学习框架 |\n| transformers | 4.45.2 | 模型加载与推理 |\n| vllm | 0.6.6.post1 | 高效LLM推理 |\n| openai | 1.91.1 | OpenAI API调用 |\n| litellm | 1.73.1 | 多模型统一接口 |\n| gritlm | 1.0.2 | 检索嵌入模型 |\n\n资料来源：[setup.py:17-29](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L17-L29)\n\n### 6.2 辅助依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| networkx | 3.4.2 | 图结构处理 |\n| python_igraph | 0.11.8 | 图算法实现 |\n| tiktoken | 0.7.0 | 分词器 |\n| pydantic | 2.10.4 | 数据验证 |\n| tenacity | 8.5.0 | 重试机制 |\n| einops | - | 张量操作 |\n| tqdm | - | 进度条 |\n\n资料来源：[requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n\n## 7 数据格式规范\n\n### 7.1 检索语料库格式\n\n```json\n[\n {\n \"title\": \"FIRST PASSAGE TITLE\",\n \"text\": \"FIRST PASSAGE TEXT\",\n \"idx\": 0\n },\n {\n \"title\": \"SECOND PASSAGE TITLE\",\n \"text\": \"SECOND PASSAGE TEXT\",\n \"idx\": 1\n }\n]\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### 7.2 查询数据格式（可选）\n\n```json\n[\n {\n \"id\": \"sample/question_1.json\",\n \"question\": \"QUESTION\",\n \"answer\": [\"ANSWER\"],\n \"answerable\": true,\n \"paragraphs\": [\n {\n \"title\": \"{SUPPORTING PASSAGE TITLE}\",\n \"text\": \"{SUPPORTING PASSAGE TEXT}\",\n \"is_supporting\": true,\n \"idx\": 0\n }\n ]\n }\n]\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 8 使用方式\n\n### 8.1 快速开始流程\n\n```mermaid\ngraph TD\n A[初始化HippoRAG实例] --> B[准备文档数据]\n B --> C[执行索引构建]\n C --> D[执行问答查询]\n D --> E[获取评估结果]\n```\n\n### 8.2 OpenAI模型使用示例\n\n```python\nfrom hipporag import HippoRAG\n\n# 准备数据\ndocs = [\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Erik Hort's birthplace is Montebello.\"\n]\n\n# 初始化实例\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# 索引构建\nhipporag.index(docs)\n\n# 问答查询\nqueries = [\"What is George Rankin's occupation?\"]\nresults = hipporag.rag_qa(queries=queries)\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### 8.3 本地vLLM部署\n\n1. 启动vLLM服务器：\n```sh\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n2. 使用HippoRAG：\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='meta-llama/Llama-3.1-8B-Instruct',\n llm_base_url='http://localhost:6578/v1'\n)\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 9 相关论文\n\n### 9.1 HippoRAG 2（ICML '25）\n\n> From RAG to Memory: Non-Parametric Continual Learning for Large Language Models\n\n- **作者**：Bernal Jiménez Gutiérrez, Yiheng Shu, Weijian Qi, Sizhe Zhou, Yu Su\n- **arXiv**：2502.14802\n\n### 9.2 HippoRAG（NeurIPS '24）\n\n> HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models\n\n- **作者**：Bernal Jiménez Gutiérrez, Yiheng Shu, Yu Gu, Michihiro Yasunaga, Yu Su\n- **OpenReview**：hkujvAPVsg\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 10 项目贡献\n\n### 10.1 贡献流程\n\n1. Fork仓库并克隆到本地\n2. 创建新分支：`git checkout -b my-contribution`\n3. 进行修改并运行测试脚本\n4. 提交更改：`git commit -m \"Add my contribution\"`\n5. 推送分支：`git push origin my-contribution`\n6. 提交Pull Request\n\n### 10.2 测试要求\n\n| 测试类型 | 测试命令 | 适用场景 |\n|---------|---------|---------|\n| OpenAI测试 | `python tests_openai.py` | 使用OpenAI LLM和嵌入模型 |\n| 本地测试 | `python tests_local.py` | 使用vLLM本地部署 |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 11 环境变量配置\n\n| 变量名 | 说明 | 示例 |\n|--------|------|------|\n| `CUDA_VISIBLE_DEVICES` | 可用GPU设备编号 | 0,1,2,3 |\n| `HF_HOME` | HuggingFace缓存目录路径 | /path/to/huggingface |\n| `OPENAI_API_KEY` | OpenAI API密钥 | sk-xxxx |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 12 TODOs与未来规划\n\n- [x] 添加更多嵌入模型支持\n- [x] 添加嵌入端点支持\n- [ ] 添加向量数据库集成支持\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 13 致谢\n\n本项目由俄亥俄州立大学（The Ohio State University）NLP研究组开发维护。\n\n**主要联系人**：\n- Bernal Jiménez Gutiérrez（jimenezgutierrez.1@osu.edu）\n- Yiheng Shu（shu.251@osu.edu）\n- Yu Su（su.809@osu.edu）\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[项目介绍](#p1), [实验复现指南](#p9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [demo_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_openai.py)\n- [demo_local.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_local.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n \n\n# 快速入门指南\n\nHippoRAG 是一个基于图的 RAG（检索增强生成）框架，能够使大型语言模型识别并利用新知识中的关联信息来改进检索效果。本文档将帮助用户在最短时间内完成环境配置和基本功能验证。\n\n## 环境要求\n\n### 系统依赖\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | ≥ 3.10 | 项目必需的 Python 版本 |\n| CUDA | 兼容 | 用于 GPU 加速推理 |\n| conda | 任意稳定版本 | 建议使用 conda 管理虚拟环境 |\n\n资料来源：[setup.py:8]()\n\n### 核心依赖包\n\n项目安装后会自动引入以下核心依赖：\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| torch | 2.5.1 | 深度学习框架 |\n| transformers | 4.45.2 | 模型推理 |\n| vllm | 0.6.6.post1 | 本地 LLM 部署 |\n| openai | 1.91.1 | OpenAI API 调用 |\n| networkx | 3.4.2 | 图数据结构 |\n| pydantic | 2.10.4 | 配置管理 |\n\n资料来源：[setup.py:14-27]()\n\n## 安装步骤\n\n### 方法一：使用 pip 直接安装（推荐）\n\n```sh\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install hipporag\n```\n\n资料来源：[README.md:67-70]()\n\n### 方法二：从源码安装\n\n```sh\ngit clone https://github.com/OSU-NLP-Group/HippoRAG.git\ncd HippoRAG\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install -e .\n```\n\n## 环境变量配置\n\n在运行项目之前，需要配置以下环境变量：\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\nexport OPENAI_API_KEY= # 仅在使用 OpenAI 模型时需要\n```\n\n| 环境变量 | 必填 | 说明 |\n|----------|------|------|\n| CUDA_VISIBLE_DEVICES | 是 | 指定使用的 GPU 编号 |\n| HF_HOME | 是 | Hugging Face 模型缓存目录 |\n| OPENAI_API_KEY | 否 | OpenAI API 密钥（使用 OpenAI 模型时必填） |\n\n资料来源：[README.md:72-76]()\n\n## 快速使用流程\n\nHippoRAG 的核心使用流程分为三个阶段：初始化、索引构建、检索与问答。\n\n```mermaid\ngraph TD\n A[初始化 HippoRAG 实例] --> B[调用 index 方法构建索引]\n B --> C[调用 rag_qa 方法进行检索问答]\n C --> D[获取检索结果和生成答案]\n```\n\n资料来源：[README.md:78-97]()\n\n### 使用 OpenAI 模型\n\n以下示例展示如何使用 OpenAI 模型进行索引构建和问答检索：\n\n```python\nfrom hipporag import HippoRAG\n\n# 准备文档数据\ndocs = [\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Cinderella attended the royal ball.\",\n \"The prince used the lost glass slipper to search the kingdom.\",\n \"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"\n]\n\n# 定义保存目录\nsave_dir = 'outputs'\n\n# 设置模型配置\nllm_model_name = 'gpt-4o-mini'\nembedding_model_name = 'nvidia/NV-Embed-v2'\n\n# 初始化 HippoRAG 实例\nhipporag = HippoRAG(save_dir=save_dir, \n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name)\n\n# 构建索引\nhipporag.index(docs=docs)\n\n# 准备查询和评估数据\nqueries = [\n \"What is George Rankin's occupation?\",\n \"How did Cinderella reach her happy ending?\",\n \"What county is Erik Hort's birthplace a part of?\"\n]\n\nanswers = [\n [\"Politician\"],\n [\"By going to the ball.\"],\n [\"Rockland County\"]\n]\n\ngold_docs = [\n [\"George Rankin is a politician.\"],\n [\"Cinderella attended the royal ball.\",\n \"The prince used the lost glass slipper to search the kingdom.\",\n \"When the slipper fit perfectly, Cinderella was reunited with the prince.\"],\n [\"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"]\n]\n\n# 执行检索和问答\nrag_results = hipporag.rag_qa(queries=queries, \n gold_docs=gold_docs,\n gold_answers=answers)\n```\n\n资料来源：[README.md:78-97]()\n\n### 使用本地 vLLM 部署\n\n#### 第一步：启动 vLLM 服务器\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nconda activate hipporag\n\n# 根据 GPU 内存调整参数\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n资料来源：[README.md:106-113]()\n\n#### 第二步：运行主程序\n\n```sh\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=\n\npython main.py --dataset sample --llm_base_url http://localhost:6578/v1 \\\n --llm_name meta-llama/Llama-3.1-8B-Instruct \\\n --embedding_name nvidia/NV-Embed-v2\n```\n\n资料来源：[README.md:115-120]()\n\n### 使用 OpenAI 兼容端点\n\n如果使用第三方 OpenAI 兼容的 LLM 和 Embedding 服务：\n\n```python\nhipporag = HippoRAG(save_dir=save_dir, \n llm_model_name='Your LLM Model name',\n llm_base_url='Your LLM Model url',\n embedding_model_name='Your Embedding model name', \n embedding_base_url='Your Embedding model url')\n```\n\n资料来源：[README.md:100-103]()\n\n### 使用 Azure OpenAI\n\n```python\nhipporag = HippoRAG(save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name,\n azure_endpoint=\"https://[ENDPOINT NAME].openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2025-01-01-preview\",\n azure_embedding_endpoint=\"https://[ENDPOINT NAME].openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2023-05-15\")\n```\n\n资料来源：[demo_openai.py:1-5]()\n\n## 核心配置参数\n\n`BaseConfig` 类包含所有可配置参数，以下是常用参数说明：\n\n| 参数名 | 默认值 | 类型 | 说明 |\n|--------|--------|------|------|\n| llm_model_name | - | str | LLM 模型名称 |\n| embedding_model_name | nvidia/NV-Embed-v2 | str | Embedding 模型名称 |\n| llm_base_url | - | str | LLM API 端点 URL |\n| embedding_base_url | - | str | Embedding API 端点 URL |\n| linking_top_k | 5 | int | 每次检索步骤链接的节点数 |\n| retrieval_top_k | 200 | int | 每次检索的文档数量 |\n| qa_top_k | 5 | int | 输入给 QA 模型的 Top-K 文档数 |\n| max_qa_steps | 1 | int | 最大问答迭代步数 |\n| openie_mode | online | str | OpenIE 模型模式（online/offline） |\n| embedding_batch_size | 16 | int | Embedding 模型批处理大小 |\n\n资料来源：[src/hipporag/utils/config_utils.py:1-50]()\n\n## 数据集格式\n\n### 检索语料库格式\n\n```json\n[\n {\n \"title\": \"FIRST PASSAGE TITLE\",\n \"text\": \"FIRST PASSAGE TEXT\",\n \"idx\": 0\n },\n {\n \"title\": \"SECOND PASSAGE TITLE\",\n \"text\": \"SECOND PASSAGE TEXT\",\n \"idx\": 1\n }\n]\n```\n\n资料来源：[README.md:141-151]()\n\n### 查询文件格式（可选）\n\n```json\n[\n {\n \"id\": \"sample/question_1.json\",\n \"question\": \"QUESTION\",\n \"answer\": [\"ANSWER\"],\n \"answerable\": true,\n \"paragraphs\": [\n {\n \"title\": \"{SUPPORTING PASSAGE TITLE}\",\n \"text\": \"{SUPPORTING PASSAGE TEXT}\",\n \"is_supporting\": true,\n \"idx\": 0\n }\n ]\n }\n]\n```\n\n资料来源：[README.md:153-170]()\n\n## 验证安装\n\n### 使用 OpenAI 模型验证\n\n```sh\nexport OPENAI_API_KEY= \nconda activate hipporag\npython tests_openai.py\n```\n\n资料来源：[README.md:124-128]()\n\n### 使用本地模型验证\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nconda activate hipporag\n\n# 启动 vLLM 服务器\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n\n# 运行测试\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:130-144]()\n\n## 常见问题排查\n\n### GPU 内存不足\n\n如果遇到 OOM（内存溢出）错误，可以调整以下参数：\n\n- 降低 `gpu-memory-utilization` 值（建议从 0.95 逐步下调）\n- 减小 `max_model_len` 参数\n- 减少 `CUDA_VISIBLE_DEVICES` 中指定的 GPU 数量\n\n资料来源：[README.md:109-112]()\n\n### 索引构建缓慢\n\n建议增加 `embedding_batch_size` 参数的值，默认值为 16，可根据 GPU 显存调整为 32 或更高。\n\n资料来源：[main.py:12]()\n\n## 后续步骤\n\n完成快速入门后，建议进一步阅读以下内容：\n\n- **高级配置**：调整 `BaseConfig` 中的参数以优化检索效果\n- **增量更新**：使用 `index` 方法对新增文档进行增量索引\n- **实验复现**：参考 `main.py` 的实现方式运行论文中的实验\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目介绍](#p1), [知识图谱构建](#p4), [LLM模型集成](#p5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)\n- [src/hipporag/StandardRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/StandardRAG.py)\n- [src/hipporag/embedding_store.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_store.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n \n\n# 系统架构设计\n\n## 概述\n\nHippoRAG是一个受神经生物学启发的图基RAG（检索增强生成）框架，旨在使大型语言模型能够识别并利用新知识中的关联信息以改进检索效果。该系统通过模拟海马体的记忆索引机制，实现高效的持久化知识管理和关联推理能力。\n\nHippoRAG的核心架构围绕三个主要阶段设计：**索引（Indexing）**、**检索（Retrieval）** 和 **问答（QA）**。系统支持多种LLM后端（OpenAI、vLLM、Azure OpenAI）和嵌入模型（NV-Embed-v2、GritLM、Contriever等），提供了灵活的部署选项。\n\n## 核心模块架构\n\n### 模块层次结构\n\nHippoRAG项目采用清晰的模块化设计，各组件职责明确：\n\n| 模块路径 | 功能描述 | 核心类/文件 |\n|---------|---------|------------|\n| `hipporag/embedding_model/` | 嵌入模型实现 | `BaseEmbeddingModel`, `NVEmbedV2` |\n| `hipporag/evaluation/` | 评估指标 | `BaseMetric`, `qa_eval.py`, `retrieval_eval.py` |\n| `hipporag/information_extraction/` | 信息抽取 | `openie_openai_gpt.py`, `openie_vllm_offline.py` |\n| `hipporag/llm/` | 大语言模型推理 | 各类LLM调用封装 |\n| `hipporag/utils/` | 工具函数 | `config_utils.py` |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### 主要类层次\n\nHippoRAG中存在两种主要的RAG实现类：\n\n```mermaid\nclassDiagram\n class BaseRAG {\n <>\n +index(docs)\n +rag_qa(queries, gold_docs, gold_answers)\n +delete(docs)\n }\n class HippoRAG {\n +index(docs)\n +rag_qa(queries, gold_docs, gold_answers)\n +delete(docs)\n }\n class StandardRAG {\n +index(docs)\n +rag_qa(queries, gold_docs, gold_answers)\n }\n \n BaseRAG <|-- HippoRAG\n BaseRAG <|-- StandardRAG\n```\n\n**HippoRAG** 类提供完整的图基索引和Personalized PageRank检索能力，而 **StandardRAG** 类实现传统的密集检索方法。\n\n## 配置系统\n\n### 配置架构\n\nHippoRAG使用Pydantic的`BaseConfig`类作为配置基础，提供类型安全的配置管理：\n\n```python\nclass BaseConfig(BaseModel):\n # OpenIE配置\n openie_mode: Literal['OpenAI', 'vLLM-offline', 'Transformers-offline']\n information_extraction_model_name: str\n \n # Embedding模型配置\n embedding_model_name: str\n embedding_batch_size: int = 16\n embedding_return_as_normalized: bool = True\n embedding_max_seq_len: int = 2048\n embedding_model_dtype: Literal[\"float16\", \"float32\", \"bfloat16\", \"auto\"]\n \n # 图构建配置\n synonymy_edge_topk: int = 2047\n synonymy_edge_query_batch_size: int = 1000\n synonymy_edge_key_batch_size: int = 10000\n synonymy_edge_sim_threshold: float = 0.8\n \n # 检索配置\n linking_top_k: int = 5\n retrieval_top_k: int = 200\n damping: float = 0.5\n \n # QA配置\n max_qa_steps: int = 1\n qa_top_k: int = 5\n \n # 保存路径\n save_dir: str = \"outputs\"\n```\n\n资料来源：[src/hipporag/utils/config_utils.py:1-100](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n### 关键配置参数\n\n#### OpenIE模式配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `openie_mode` | str | - | 信息抽取模式：OpenAI/vLLM-offline/Transformers-offline |\n| `information_extraction_model_name` | str | - | 信息抽取使用的模型名称 |\n\n#### 嵌入模型配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `embedding_model_name` | str | - | 嵌入模型名称（nvidia/NV-Embed-v2等） |\n| `embedding_batch_size` | int | 16 | 嵌入调用批次大小 |\n| `embedding_return_as_normalized` | bool | True | 是否返回归一化嵌入 |\n| `embedding_max_seq_len` | int | 2048 | 嵌入模型最大序列长度 |\n| `embedding_model_dtype` | str | \"auto\" | 模型数据类型 |\n\n#### 图构建配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `synonymy_edge_topk` | int | 2047 | 构建同义边时的KNN检索K值 |\n| `synonymy_edge_query_batch_size` | int | 1000 | 同义边查询批大小 |\n| `synonymy_edge_key_batch_size` | int | 10000 | 同义边键批大小 |\n| `synonymy_edge_sim_threshold` | float | 0.8 | 同义边相似度阈值 |\n| `is_directed_graph` | bool | False | 图是否是有向图 |\n\n#### 检索与QA配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `linking_top_k` | int | 5 | 每次检索步骤关联的节点数 |\n| `retrieval_top_k` | int | 200 | 初始检索文档数 |\n| `damping` | float | 0.5 | PageRank阻尼因子 |\n| `max_qa_steps` | int | 1 | QA最大迭代步数 |\n| `qa_top_k` | int | 5 | 输入QA模型的顶部文档数 |\n\n## 索引流程架构\n\n### 索引阶段工作流\n\nHippoRAG的索引阶段将文档转化为知识图谱，实现与海马体记忆索引类似的持久化存储：\n\n```mermaid\ngraph TD\n A[输入文档列表] --> B[文本分割]\n B --> C[OpenIE信息抽取]\n C --> D[生成事实三元组]\n D --> E[实体节点提取]\n E --> F[构建段落节点]\n F --> G[生成实体-段落边]\n G --> H[KNN同义边构建]\n H --> I[段落相似边构建]\n I --> J[持久化图结构存储]\n \n C --> K[文档嵌入生成]\n K --> L[向量存储]\n```\n\n### 核心索引组件\n\nHippoRAG使用`embedding_store`模块管理向量存储，该模块负责：\n\n1. **文档嵌入**：使用配置的嵌入模型对文档进行向量化\n2. **向量索引**：构建高效的向量检索索引\n3. **相似度计算**：支持归一化和非归一化嵌入的相似度计算\n\n索引过程的关键调用示例：\n\n```python\n# main.py中的索引调用\nhipporag = HippoRAG(global_config=config)\nhipporag.index(docs)\n```\n\n资料来源：[main.py:1-30](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n## 检索流程架构\n\n### Personalized PageRank检索\n\nHippoRAG采用Personalized PageRank（PPR）算法进行关联检索，区别于传统的向量相似度检索：\n\n```mermaid\ngraph LR\n A[查询] --> B[向量相似度检索]\n B --> C[获取初始候选节点]\n C --> D[构建查询图]\n D --> E[PPR迭代计算]\n E --> F[节点重要性排序]\n F --> G[返回关联段落]\n```\n\n### 检索配置参数\n\n| 参数 | 说明 | 影响 |\n|------|------|------|\n| `retrieval_top_k` | 初始向量检索返回的文档数 | 候选集大小，影响PPR计算范围 |\n| `linking_top_k` | 每步关联的节点数 | 检索的深度和广度 |\n| `damping` | PPR阻尼因子 | 随机跳转概率，影响收敛速度 |\n| `synonymy_edge_sim_threshold` | 同义边相似度阈值 | 控制哪些实体被视为同义 |\n\n检索过程中，系统通过同义边（synonymy edges）建立实体间的语义关联，实现跨段落的事实关联发现。\n\n## 问答流程架构\n\n### 多步推理问答\n\nHippoRAG支持迭代式问答，通过多步检索-推理交替提升答案质量：\n\n```mermaid\ngraph TD\n A[问题输入] --> B[Step 1: 检索相关段落]\n B --> C[Step 1: LLM推理]\n C --> D{达到最大步数?}\n D -->|否| E[基于推理结果重检索]\n E --> B\n D -->|是| F[生成最终答案]\n B --> G[Top-K段落收集]\n G --> F\n```\n\n### QA配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `max_qa_steps` | 1 | 最大问答迭代步数 |\n| `qa_top_k` | 5 | 输入LLM的顶部文档数 |\n\n调用示例：\n\n```python\nrag_results = hipporag.rag_qa(\n queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers\n)\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 部署架构\n\n### 多后端支持\n\nHippoRAG支持多种LLM和嵌入模型部署方式：\n\n#### OpenAI模型部署\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n```\n\n#### Azure OpenAI部署\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\n azure_endpoint=\"https://[ENDPOINT].openai.azure.com/...\",\n azure_embedding_endpoint=\"https://[ENDPOINT].openai.azure.com/...\"\n)\n```\n\n#### vLLM本地部署\n\n```bash\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='meta-llama/Llama-3.1-8B-Instruct',\n llm_model_port=6578,\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n```\n\n### 依赖架构\n\nHippoRAG的核心依赖层次：\n\n| 依赖层级 | 库 | 版本 | 用途 |\n|---------|-----|------|------|\n| 深度学习框架 | torch | 2.5.1 | Tensor计算 |\n| 推理框架 | vLLM | 0.6.6.post1 | 本地LLM推理 |\n| 嵌入模型 | transformers | 4.45.2 | 模型加载 |\n| 图计算 | networkx | 3.4.2 | 图结构操作 |\n| 图算法 | python_igraph | 0.11.8 | 图算法实现 |\n| API调用 | openai | 1.91.1 | OpenAI API |\n| 向量嵌入 | gritlm | 1.0.2 | GritLM嵌入模型 |\n| 数据验证 | pydantic | 2.10.4 | 配置管理 |\n| 重试机制 | tenacity | 8.5.0 | 容错处理 |\n| 分词 | tiktoken | 0.7.0 | Token计数 |\n\n资料来源：[setup.py:1-30](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n\n## 数据流架构\n\n### 完整RAG流程\n\n```mermaid\nflowchart TB\n subgraph 索引阶段[\"索引阶段\"]\n I1[加载配置] --> I2[文档预处理]\n I2 --> I3[OpenIE抽取]\n I3 --> I4[构建事实图谱]\n I4 --> I5[向量索引]\n I5 --> I6[持久化存储]\n end\n \n subgraph 检索阶段[\"检索阶段\"]\n Q1[用户查询] --> Q2[查询向量化]\n Q2 --> Q3[向量相似度检索]\n Q3 --> Q4[初始候选集]\n Q4 --> Q5[PPR图遍历]\n Q5 --> Q6[关联段落排序]\n end\n \n subgraph QA阶段[\"问答阶段\"]\n QA1[相关段落] --> QA2[Prompt构建]\n QA2 --> QA3[LLM推理]\n QA3 --> QA4{迭代判断}\n QA4 -->|继续| QA5[重检索]\n QA5 --> QA2\n QA4 -->|完成| QA6[答案生成]\n end\n \n I6 --> Q1\n Q6 --> QA1\n```\n\n## 项目结构\n\n```\nsrc/hipporag/\n├── HippoRAG.py # 核心HippoRAG类实现\n├── StandardRAG.py # 标准RAG实现\n├── embedding_store.py # 向量存储管理\n├── __init__.py\n├── embedding_model/ # 嵌入模型模块\n│ ├── __init__.py\n│ ├── base.py # 基类定义\n│ └── NVEmbedV2.py # NV-Embed-v2实现\n├── evaluation/ # 评估模块\n│ ├── __init__.py\n│ ├── base.py # 评估基类\n│ ├── qa_eval.py # QA评估\n│ └── retrieval_eval.py # 检索评估\n├── information_extraction/ # 信息抽取模块\n│ ├── __init__.py\n│ ├── openie_openai_gpt.py\n│ └── openie_vllm_offline.py\n├── llm/ # LLM推理模块\n└── utils/\n ├── __init__.py\n └── config_utils.py # 配置工具\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 总结\n\nHippoRAG的系统架构设计体现了以下核心原则：\n\n1. **模块化设计**：各功能模块（嵌入模型、信息抽取、图构建、检索、QA）职责清晰，便于扩展和维护\n\n2. **配置驱动**：通过`BaseConfig`类实现类型安全的配置管理，支持多种部署场景\n\n3. **海马体启发的持久化索引**：通过OpenIE抽取事实知识并构建异构图，实现长期记忆的持久化存储\n\n4. **PPR关联检索**：采用Personalized PageRank算法挖掘实体间的语义关联，克服传统向量检索的局限性\n\n5. **多后端兼容**：统一接口支持OpenAI、vLLM、Azure等多种部署方式，提高系统灵活性\n\n---\n\n\n\n## 知识图谱构建\n\n### 相关页面\n\n相关主题：[系统架构设计](#p3), [OpenIE信息抽取](#p7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py) (README.md中的代码结构引用)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py) (使用示例)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py) (依赖声明)\n \n\n# 知识图谱构建\n\nHippoRAG的知识图谱构建是整个框架的核心组件，负责将原始文档语料转化为结构化的图知识表示。该模块整合了开放信息抽取（OpenIE）、嵌入向量计算和图连接构建等技术，实现了类似人类海马体的知识组织和关联机制。\n\n## 核心配置参数\n\n知识图谱构建通过`BaseConfig`类进行配置管理，主要涉及以下关键参数：\n\n| 参数名称 | 默认值 | 说明 |\n|---------|--------|------|\n| `graph_type` | `facts_and_sim_passage_node_unidirectional` | 图类型，定义节点和边的组织方式 |\n| `openie_mode` | `openai-gpt` | 开放信息抽取模式 |\n| `information_extraction_model_name` | `gpt-4o-mini` | 信息抽取使用的模型名称 |\n| `synonymy_edge_topk` | `2047` | 构建同义词边时KNN检索的K值 |\n| `synonymy_edge_sim_threshold` | `0.8` | 同义词边的相似度阈值 |\n| `is_directed_graph` | `False` | 图是否为有向图 |\n\n资料来源：[config_utils.py:参数定义](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n## 图谱构建流程\n\n知识图谱的构建遵循以下标准化流程：\n\n```mermaid\ngraph TD\n A[原始文档输入] --> B[分块与预处理]\n B --> C[开放信息抽取 OpenIE]\n C --> D[事实三元组提取]\n C --> E[段落节点创建]\n D --> F[事实节点与段落节点连接]\n E --> F\n F --> G[嵌入向量计算]\n G --> H[同义词边构建 KNN]\n H --> I[个性化PageRank检索准备]\n I --> J[知识图谱输出]\n```\n\n1. **文档输入与预处理**：接收原始文本语料，按照配置进行必要的分块处理\n2. **开放信息抽取**：使用OpenIE模型从文本中提取事实三元组（主语-谓词-宾语）\n3. **节点创建**：生成两类核心节点——事实节点（Fact Node）和段落节点（Passage Node）\n4. **边构建**：基于语义相似度和实体关联建立节点间的连接关系\n5. **图谱索引**：完成图结构的持久化存储，为后续检索做好准备\n\n资料来源：[README.md:代码结构](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 图类型配置\n\nHippoRAG支持多种图谱拓扑结构，通过`graph_type`参数进行选择：\n\n| 图类型 | 描述 | 适用场景 |\n|-------|------|---------|\n| `facts_and_sim_passage_node_unidirectional` | 事实节点与段落节点单向连接，含同义词边 | 默认配置，适合大多数问答场景 |\n| `facts_and_sim_passage_node_bidirectional` | 事实节点与段落节点双向连接 | 需要更密集的信息流动 |\n| `facts_passage_node` | 仅含事实边和段落节点 | 轻量级图谱，减少计算开销 |\n\n同义词边的构建采用KNN（K近邻）算法，在嵌入向量空间中寻找语义相似的节点对：\n\n```python\nsynonymy_edge_topk: int = 2047 # KNN检索的K值\nsynonymy_edge_query_batch_size: int = 1000 # 查询嵌入批次大小\nsynonymy_edge_key_batch_size: int = 10000 # 键嵌入批次大小\nsynonymy_edge_sim_threshold: float = 0.8 # 相似度阈值\n```\n\n资料来源：[config_utils.py:图构建参数](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n## 开放信息抽取模式\n\nHippoRAG支持两种OpenIE实现方式：\n\n| 模式 | 说明 | 依赖 |\n|------|------|------|\n| `openai-gpt` | 使用OpenAI GPT模型进行信息抽取 | `OPENAI_API_KEY`环境变量 |\n| `vllm-offline` | 使用本地vLLM部署的模型 | vLLM服务配置 |\n| `Transformers-offline` | 使用Transformers库本地加载模型 | GPU显存充足 |\n\n信息抽取模块位于`src/hipporag/information_extraction/`目录，包含以下实现：\n\n- `openie_openai_gpt.py`：OpenAI GPT模型的OpenIE实现\n- `openie_vllm_offline.py`：vLLM离线部署模型的OpenIE实现\n\n资料来源：[README.md:信息抽取模块](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 索引构建接口\n\nHippoRAG通过`HippoRAG`类提供统一的索引构建接口：\n\n```python\nfrom hipporag import HippoRAG\n\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# 文档索引构建\nhipporag.index(docs=[\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Erik Hort's birthplace is Montebello.\"\n])\n```\n\n配置参数可通过`global_config`或构造函数直接传入：\n\n```python\nconfig = BaseConfig(\n graph_type=\"facts_and_sim_passage_node_unidirectional\",\n synonymy_edge_topk=2047,\n synonymy_edge_sim_threshold=0.8,\n embedding_batch_size=8,\n openie_mode='openai-gpt',\n information_extraction_model_name='gpt-4o-mini'\n)\n\nhipporag = HippoRAG(global_config=config, ...)\n```\n\n资料来源：[main.py:索引配置](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n## 嵌入模型配置\n\n图谱构建过程中的向量计算支持多种嵌入模型：\n\n| 模型类型 | 模型名称示例 | 配置方式 |\n|---------|-------------|---------|\n| NVIDIA | `nvidia/NV-Embed-v2` | 直接指定模型名 |\n| GritLM | `GritLM` | 通过`embedding_model_name`指定 |\n| Contriever | `Contriever` | 通过`embedding_model_name`指定 |\n| OpenAI兼容 | 自定义模型 | `embedding_base_url`指定端点 |\n| Azure OpenAI | `text-embedding-3-small` | `azure_embedding_endpoint`配置 |\n\n嵌入相关配置参数：\n\n| 参数 | 默认值 | 说明 |\n|-----|--------|------|\n| `embedding_batch_size` | 16 | 嵌入计算的批次大小 |\n| `embedding_return_as_normalized` | True | 是否返回归一化向量 |\n| `embedding_max_seq_len` | 2048 | 最大序列长度 |\n| `embedding_model_dtype` | `auto` | 数据类型（float16/float32/bfloat16/auto） |\n\n资料来源：[config_utils.py:嵌入配置](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n## 依赖组件\n\n知识图谱构建依赖以下核心库：\n\n| 依赖库 | 版本 | 用途 |\n|-------|------|------|\n| `networkx` | 3.4.2 | 图数据结构与算法实现 |\n| `python_igraph` | 0.11.8 | 图可视化与分析 |\n| `torch` | 2.5.1 | 深度学习张量计算 |\n| `transformers` | 4.45.2 | 预训练模型加载 |\n| `gritlm` | 1.0.2 | GritLM嵌入模型支持 |\n| `tiktoken` | 0.7.0 | Tokenization |\n| `pydantic` | 2.10.4 | 配置数据验证 |\n\n资料来源：[setup.py:依赖声明](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n\n## 增量更新与删除\n\nHippoRAG支持对已构建的图谱进行增量操作：\n\n```python\n# 添加新文档\nhipporag.index(docs=[\"新文档内容...\"])\n\n# 删除指定文档\nhipporag.delete(docs_to_delete=[\"要删除的文档...\"])\n\n# 验证更新效果\nresult = hipporag.rag_qa(queries=queries, \n gold_docs=gold_docs, \n gold_answers=answers)\n```\n\n增量更新会重新计算相关节点的嵌入向量，并更新图中的连接关系。\n\n资料来源：[tests_openai.py:增量操作](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)\n\n## 环境变量配置\n\n图谱构建前需正确配置以下环境变量：\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0,1,2,3 # GPU设备选择\nexport HF_HOME= # HuggingFace模型缓存目录\nexport OPENAI_API_KEY= # OpenAI API密钥（使用OpenAI模式时）\n```\n\n资料来源：[README.md:环境配置](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n---\n\n\n\n## LLM模型集成\n\n### 相关页面\n\n相关主题：[系统架构设计](#p3), [Embedding模型集成](#p6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/llm/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)\n- [src/hipporag/llm/openai_gpt.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/openai_gpt.py)\n- [src/hipporag/llm/vllm_offline.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/vllm_offline.py)\n- [src/hipporag/llm/bedrock_llm.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/bedrock_llm.py)\n- [src/hipporag/llm/transformers_llm.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/transformers_llm.py)\n \n\n# LLM模型集成\n\n## 概述\n\nHippoRAG的LLM模型集成模块提供了一套统一的接口，用于对接多种大语言模型提供商。该模块位于`src/hipporag/llm/`目录下，通过抽象基类`LLMInterface`定义标准接口，各具体实现类继承该基类以支持不同的模型服务。\n\n主要支持以下模型服务：\n\n| 提供商 | 实现类 | 特点 |\n|--------|--------|------|\n| OpenAI | `OpenAIGPT` | 云端API调用，支持自定义endpoint |\n| vLLM | `VLLMOffline` | 本地离线推理，高吞吐量 |\n| AWS Bedrock | `BedrockLLM` | 云端托管，支持Claude等模型 |\n| HuggingFace Transformers | `TransformersLLM` | 本地transformers库推理 |\n\n资料来源：[base.py:1-20](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)\n\n## 架构设计\n\n### 类层次结构\n\nHippoRAG采用面向对象设计模式，通过抽象基类定义统一接口规范：\n\n```mermaid\ngraph TD\n A[LLMInterface
抽象基类] --> B[OpenAIGPT]\n A --> C[VLLMOffline]\n A --> D[BedrockLLM]\n A --> E[TransformersLLM]\n \n F[调用方] --> A\n```\n\n### 接口规范\n\n`LLMInterface`定义了所有LLM实现必须遵循的核心方法：\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `__call__` | `prompt`, `system_prompt`, `keyword` | `str` | 同步调用接口 |\n| `batch_call` | `prompts`, `system_prompts`, `keywords` | `List[str]` | 批量调用接口 |\n| `_call` | `prompt`, `system_prompt`, `keyword` | `str` | 具体实现方法 |\n| `_batch_call` | `prompts`, `system_prompts`, `keywords` | `List[str]` | 批量实现方法 |\n\n资料来源：[base.py:10-60](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)\n\n## 核心实现\n\n### 基础抽象类\n\n基础类`LLMInterface`位于`base.py`，采用ABC抽象基类模式：\n\n```python\nclass LLMInterface(ABC):\n def __init__(\n self,\n model_name: str,\n api_key: str = None,\n api_base: str = None,\n timeout: int = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\n关键配置参数说明：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model_name` | `str` | 必填 | 模型标识符 |\n| `api_key` | `str` | `None` | API密钥 |\n| `api_base` | `str` | `None` | API服务端点 |\n| `timeout` | `int` | `120` | 超时时间（秒） |\n| `max_tokens` | `int` | `256` | 最大生成token数 |\n| `temperature` | `float` | `0.0` | 采样温度 |\n| `request_timeout` | `int` | `120` | 请求超时 |\n| `top_p` | `float` | `1.0` | 核采样概率 |\n\n资料来源：[base.py:10-25](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)\n\n### OpenAI GPT集成\n\n`OpenAIGPT`类封装了OpenAI API的调用逻辑：\n\n```python\nclass OpenAIGPT(LiteLLM):\n def __init__(\n self,\n model_name: str = \"gpt-3.5-turbo\",\n api_key: str = None,\n api_base: str = None,\n timeout: float = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\n支持的模型包括：\n- `gpt-4`\n- `gpt-4-turbo`\n- `gpt-4o`\n- `gpt-3.5-turbo`\n- `gpt-3.5-turbo-16k`\n\n资料来源：[openai_gpt.py:15-40](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/openai_gpt.py)\n\n### vLLM离线推理\n\n`VLLMOffline`类支持本地vLLM服务器推理，适用于需要离线或私有化部署的场景：\n\n```python\nclass VLLMOffline(LiteLLM):\n def __init__(\n self,\n model_name: str,\n api_base: str,\n api_key: str = \"EMPTY\",\n timeout: float = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\n特点：\n- 默认使用`api_key = \"EMPTY\"`简化本地部署认证\n- 支持批量请求提升吞吐量\n- 可对接任何兼容OpenAI API格式的vLLM服务端\n\n资料来源：[vllm_offline.py:1-50](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/vllm_offline.py)\n\n### AWS Bedrock集成\n\n`BedrockLLM`类提供对AWS Bedrock平台模型的支持：\n\n```python\nclass BedrockLLM(LiteLLM):\n def __init__(\n self,\n model_name: str,\n aws_access_key: str = None,\n aws_secret_key: str = None,\n aws_region_name: str = \"us-east-1\",\n timeout: float = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\nAWS特定配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `aws_access_key` | `str` | `None` | AWS访问密钥 |\n| `aws_secret_key` | `str` | `None` | AWS秘密密钥 |\n| `aws_region_name` | `str` | `\"us-east-1\"` | AWS区域 |\n\n支持的Bedrock模型：\n- Claude系列（通过Anthropic）\n- Titan系列\n- Llama系列\n\n资料来源：[bedrock_llm.py:1-60](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/bedrock_llm.py)\n\n### HuggingFace Transformers\n\n`TransformersLLM`类支持直接使用HuggingFace transformers库进行本地推理：\n\n```python\nclass TransformersLLM(LiteLLM):\n def __init__(\n self,\n model_name: str,\n model_path: str = None,\n auth_token: str = None,\n device: str = \"cuda\",\n timeout: float = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\nHuggingFace特定配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model_name` | `str` | 必填 | HuggingFace模型标识 |\n| `model_path` | `str` | `None` | 本地模型路径 |\n| `auth_token` | `str` | `None` | HuggingFace认证令牌 |\n| `device` | `str` | `\"cuda\"` | 运行设备（cuda/cpu） |\n\n资料来源：[transformers_llm.py:1-60](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/transformers_llm.py)\n\n## 使用流程\n\n### 初始化与调用流程\n\n```mermaid\ngraph TD\n A[选择LLM类型] --> B{场景需求}\n B -->|云端API| C[OpenAIGPT / BedrockLLM]\n B -->|本地推理| D{vLLM or Transformers}\n D -->|批量高吞吐| E[VLLMOffline]\n D -->|灵活部署| F[TransformersLLM]\n \n C --> G[配置API密钥和端点]\n E --> H[启动vLLM服务]\n F --> I[下载/加载模型]\n \n G --> J[实例化LLM对象]\n H --> J\n I --> J\n \n J --> K[调用__call__方法]\n K --> L[返回生成结果]\n```\n\n### 代码示例\n\n```python\nfrom hipporag.llm import OpenAIGPT, VLLMOffline, TransformersLLM\n\n# OpenAI API调用\nllm = OpenAIGPT(\n model_name=\"gpt-4\",\n api_key=\"your-api-key\",\n temperature=0.0,\n max_tokens=256\n)\nresponse = llm(\"你的问题\", system_prompt=\"你是一个助手\")\n\n# vLLM离线调用\nllm_offline = VLLMOffline(\n model_name=\"meta-llama/Llama-2-7b-chat-hf\",\n api_base=\"http://localhost:8000/v1\",\n temperature=0.0\n)\nresponse = llm_offline(\"你的问题\")\n```\n\n## 配置选项汇总\n\n| 配置项 | 适用类 | 说明 |\n|--------|--------|------|\n| `model_name` | 所有 | 模型名称或路径 |\n| `api_key` | OpenAI/Bedrock/vLLM | 认证密钥 |\n| `api_base` | OpenAI/vLLM | API服务端点 |\n| `aws_access_key` | Bedrock | AWS访问密钥 |\n| `aws_secret_key` | Bedrock | AWS秘密密钥 |\n| `aws_region_name` | Bedrock | AWS区域 |\n| `auth_token` | Transformers | HuggingFace令牌 |\n| `model_path` | Transformers | 本地模型路径 |\n| `device` | Transformers | 计算设备 |\n| `timeout` | 所有 | 超时时间（秒） |\n| `max_tokens` | 所有 | 最大生成长度 |\n| `temperature` | 所有 | 采样温度 |\n| `top_p` | 所有 | 核采样参数 |\n| `request_timeout` | 所有 | 请求超时 |\n\n## 扩展开发\n\n如需添加新的LLM提供商，可按以下步骤扩展：\n\n1. 创建新文件如`src/hipporag/llm/custom_llm.py`\n2. 继承`LLMInterface`抽象基类\n3. 实现`_call`和`_batch_call`抽象方法\n4. 在模块`__init__.py`中导出新类\n\n```python\nfrom hipporag.llm.base import LLMInterface\n\nclass CustomLLM(LLMInterface):\n def _call(self, prompt, system_prompt, keyword):\n # 实现具体的模型调用逻辑\n pass\n \n def _batch_call(self, prompts, system_prompts, keywords):\n # 实现批量调用逻辑\n pass\n```\n\n## 注意事项\n\n- 所有LLM实现类都继承自`LiteLLM`，其底层封装了lite-llm库以提供统一的调用方式\n- `temperature`和`top_p`参数影响生成多样性，通常RAG场景使用`temperature=0.0`以获得确定性结果\n- vLLM和Transformers适合需要数据隐私或控制推理环境的场景\n- AWS Bedrock需要正确配置AWS凭证和区域信息\n\n---\n\n\n\n## Embedding模型集成\n\n### 相关页面\n\n相关主题：[系统架构设计](#p3), [LLM模型集成](#p5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/embedding_model/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/base.py)\n- [src/hipporag/embedding_model/NVEmbedV2.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/NVEmbedV2.py)\n- [src/hipporag/embedding_model/GritLM.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/GritLM.py)\n- [src/hipporag/embedding_model/Transformers.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/Transformers.py)\n- [src/hipporag/embedding_model/VLLM.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/VLLM.py)\n- [src/hipporag/embedding_model/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/__init__.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)\n \n\n# Embedding模型集成\n\n## 概述\n\nHippoRAG的Embedding模型集成模块负责将文本转换为高维向量表示，以便在知识图谱构建和检索过程中进行语义相似度计算。该模块采用策略模式设计，通过抽象基类 `BaseEmbeddingModel` 定义统一接口，支持多种嵌入模型后端的灵活切换。资料来源：[src/hipporag/embedding_model/base.py:1-20]()\n\nEmbedding模型在HippoRAG系统中承担三项核心职责：\n\n- **文档编码**：将输入文档、段落和实体转换为向量表示，用于构建向量存储\n- **查询编码**：将用户查询转换为向量，以便进行语义检索\n- **KNN检索**：基于向量相似度进行最近邻搜索，支持同义词边构建和实体链接\n\n## 架构设计\n\n### 模块结构\n\n```\n📦 src/hipporag/embedding_model/\n├── __init__.py # 模型选择器，提供 get_embedding_model 函数\n├── base.py # 基类 BaseEmbeddingModel 和 EmbeddingConfig\n├── NVEmbedV2.py # NVIDIA NV-Embed-v2 模型实现\n├── GritLM.py # GritLM 模型实现\n├── Transformers.py # HuggingFace Transformers 模型实现\n└── VLLM.py # vLLM 服务嵌入模型实现\n```\n\n资料来源：[README.md - Code Structure]()\n\n### 类层次结构\n\n```mermaid\ngraph TD\n A[BaseEmbeddingModel] --> B[NVEmbedV2Model]\n A --> C[GritLMModel]\n A --> D[TransformersEmbeddingModel]\n A --> E[VLLMEmbeddingModel]\n \n F[HippoRAG] --> A\n G[EmbeddingStore] --> A\n```\n\n### 嵌入模型选择流程\n\n```mermaid\ngraph TD\n A[初始化 HippoRAG] --> B{embedding_model_name 前缀判断}\n B -->|\"nvidia/NV-Embed\"| C[NVEmbedV2Model]\n B -->|\"GritLM/\"| D[GritLMModel]\n B -->|\"Transformers/\"| E[TransformersEmbeddingModel]\n B -->|\"VLLM/\"| F[VLLMEmbeddingModel]\n B -->|其他| G[默认模型]\n \n C --> H[加载本地模型]\n D --> I[加载 GritLM]\n E --> J[加载 SentenceTransformer]\n F --> K[连接 vLLM 服务]\n```\n\n## 基础抽象类\n\n### BaseEmbeddingModel\n\n`BaseEmbeddingModel` 是所有嵌入模型的基类，定义了统一的接口规范。所有具体实现必须继承此类并实现核心方法。\n\n#### 核心属性\n\n| 属性名 | 类型 | 说明 |\n|--------|------|------|\n| `embedding_type` | str | 嵌入向量的数据类型标识，如 \"float\" |\n| `batch_size` | int | 默认批处理大小 |\n| `search_query_instr` | set | 查询指令集合，用于区分不同检索任务 |\n\n资料来源：[src/hipporag/embedding_model/base.py:1-30]()\n\n#### 核心方法\n\n| 方法名 | 参数 | 返回值 | 说明 |\n|--------|------|--------|------|\n| `encode` | texts: List[str] | np.array | 单次调用编码单个文本批次 |\n| `batch_encode` | texts: List[str], **kwargs | np.array | 分批编码大量文本，支持进度显示 |\n\n```python\nclass BaseEmbeddingModel(ABC):\n @abstractmethod\n def encode(self, texts: List[str]) -> np.array:\n \"\"\"将文本列表编码为嵌入向量\"\"\"\n pass\n \n def batch_encode(self, texts: List[str], **kwargs) -> np.array:\n \"\"\"分批编码，默认实现为循环调用 encode\"\"\"\n pass\n```\n\n## 支持的嵌入模型\n\n### 1. NV-Embed-v2\n\nNVIDIA的NV-Embed-v2是高性能嵌入模型，支持本地部署和量化推理。\n\n#### 初始化参数\n\n| 参数 | 来源配置 | 默认值 | 说明 |\n|------|----------|--------|------|\n| `global_config` | 必填 | - | 全局配置对象 |\n| `embedding_model_name` | 必填 | - | 模型名称，格式为 \"nvidia/NV-Embed-v2\" |\n\n#### 关键实现\n\n```python\nclass NVEmbedV2Model(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name\n self.model = AutoModel.from_pretrained(\n self.model_id,\n trust_remote_code=True,\n device_map=\"cuda\"\n )\n self.batch_size = 32\n```\n\n#### 特性\n\n- 支持 HuggingFace `AutoModel` 接口\n- 自动设备映射到 CUDA\n- 使用 `trust_remote_code=True` 加载自定义模型代码\n- 支持批处理编码，默认批次大小为32\n\n资料来源：[src/hipporag/embedding_model/NVEmbedV2.py:1-40]()\n\n### 2. GritLM\n\nGritLM 是专门用于检索和生成的统一嵌入模型。\n\n#### 初始化参数\n\n| 参数 | 来源配置 | 默认值 | 说明 |\n|------|----------|--------|------|\n| `global_config` | 必填 | - | 全局配置对象 |\n| `embedding_model_name` | 必填 | - | 模型名称，格式为 \"GritLM/...\" |\n\n#### 关键实现\n\n```python\nclass GritLMModel(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name[len(\"GritLM/\"):]\n self.model = GritLM(model_id=self.model_id)\n```\n\n#### 特性\n\n- 使用 `gritlm` 库实现\n- 支持检索和生成双重任务\n- 继承 GritLM 库的默认优化设置\n\n资料来源：[src/hipporag/embedding_model/GritLM.py:1-25]()\n\n### 3. Transformers (HuggingFace)\n\n通过 `SentenceTransformer` 支持所有 HuggingFace 模型。\n\n#### 初始化参数\n\n| 参数 | 来源配置 | 默认值 | 说明 |\n|------|----------|--------|------|\n| `global_config` | 必填 | - | 全局配置对象 |\n| `embedding_model_name` | 必填 | - | 模型名称，格式为 \"Transformers/模型ID\" |\n\n#### 关键实现\n\n```python\nclass TransformersEmbeddingModel(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name[len(\"Transformers/\"):]\n self.model = SentenceTransformer(\n self.model_id,\n device=\"cuda\" if torch.cuda.is_available() else \"cpu\"\n )\n self.batch_size = 64\n```\n\n#### 特性\n\n- 使用 `sentence-transformers` 库\n- 自动检测 CUDA 可用性\n- 默认批处理大小为64\n- 支持数千种 SentenceTransformer 模型\n\n资料来源：[src/hipporag/embedding_model/Transformers.py:1-30]()\n\n### 4. VLLM (远程服务)\n\n支持连接 OpenAI 兼容的 vLLM 嵌入服务端点。\n\n#### 初始化参数\n\n| 参数 | 来源配置 | 默认值 | 说明 |\n|------|----------|--------|------|\n| `global_config` | 必填 | - | 全局配置对象，需包含 `embedding_base_url` |\n| `embedding_model_name` | 必填 | - | 模型名称，格式为 \"VLLM/模型名\" |\n\n#### 关键实现\n\n```python\nclass VLLMEmbeddingModel(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name[len(\"VLLM/\"):]\n self.url = global_config.embedding_base_url\n \n def call_model(self, input_text):\n payload = {\n \"model\": self.model_id,\n \"input\": input_text,\n }\n response = requests.post(self.url, json=payload)\n return np.array([response[\"data\"][i][\"embedding\"] \n for i in range(len(response[\"data\"]))])\n```\n\n#### 特性\n\n- 通过 REST API 连接远程服务\n- 使用 OpenAI 兼容的 `/v1/embeddings` 接口\n- 支持自定义服务端点配置\n\n资料来源：[src/hipporag/embedding_model/VLLM.py:1-40]()\n\n## 配置参数\n\n嵌入模型相关的配置通过 `BaseConfig` 类管理。\n\n### 嵌入模型配置项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `embedding_batch_size` | int | 16 | 调用嵌入模型的批次大小 |\n| `embedding_return_as_normalized` | bool | True | 是否返回归一化嵌入向量 |\n| `embedding_max_seq_len` | int | 2048 | 嵌入模型的最大序列长度 |\n| `embedding_model_dtype` | str | \"auto\" | 数据类型，可选 float16/float32/bfloat16/auto |\n| `synonymy_edge_topk` | int | 2047 | 构建同义词边时的 KNN 检索数量 |\n| `synonymy_edge_query_batch_size` | int | 1000 | 同义词边构建的查询批次大小 |\n| `synonymy_edge_key_batch_size` | int | 10000 | 同义词边构建的键批次大小 |\n| `synonymy_edge_sim_threshold` | float | 0.8 | 同义词相似度阈值 |\n\n资料来源：[src/hipporag/utils/config_utils.py:1-50]()\n\n## 使用方式\n\n### 模型选择器\n\n通过前缀自动选择对应的嵌入模型实现：\n\n```python\nfrom hipporag.embedding_model import get_embedding_model\n\n# 获取嵌入模型实例\nembedding_model = get_embedding_model(\n global_config=config,\n embedding_model_name=\"nvidia/NV-Embed-v2\"\n)\n```\n\n#### 前缀映射表\n\n| 前缀 | 模型类 | 用途 |\n|------|--------|------|\n| `nvidia/NV-Embed` | NVEmbedV2Model | NVIDIA 高性能嵌入 |\n| `GritLM/` | GritLMModel | 检索生成统一模型 |\n| `Transformers/` | TransformersEmbeddingModel | HuggingFace 模型 |\n| `VLLM/` | VLLMEmbeddingModel | vLLM 远程服务 |\n\n资料来源：[src/hipporag/embedding_model/__init__.py:1-30]()\n\n### 完整使用示例\n\n#### OpenAI 兼容模型\n\n```python\nfrom hipporag import HippoRAG\n\nhipporag = HippoRAG(\n save_dir=\"outputs\",\n llm_model_name=\"gpt-4o-mini\",\n llm_base_url=\"https://api.openai.com/v1\",\n embedding_model_name=\"nvidia/NV-Embed-v2\",\n embedding_base_url=\"https://api.openai.com/v1\"\n)\n\n# 执行索引和检索\nhipporag.index(docs=documents)\nresults = hipporag.rag_qa(queries=queries)\n```\n\n#### 本地 vLLM 模型\n\n```bash\n# 启动 vLLM 嵌入服务\nvllm serve nvidia/NV-Embed-v2 --port 8080\n```\n\n```python\nhipporag = HippoRAG(\n save_dir=\"outputs\",\n llm_model_name=\"meta-llama/Llama-3.1-8B-Instruct\",\n llm_base_url=\"http://localhost:6578/v1\",\n embedding_model_name=\"VLLM/nvidia/NV-Embed-v2\",\n embedding_base_url=\"http://localhost:8080/v1/embeddings\"\n)\n```\n\n## 与HippoRAG集成\n\n### 初始化流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant HippoRAG\n participant EmbeddingModel\n participant EmbeddingStore\n \n User->>HippoRAG: __init__(embedding_model_name)\n HippoRAG->>EmbeddingModel: get_embedding_model()\n HippoRAG->>EmbeddingStore: 创建向量存储\n EmbeddingStore->>EmbeddingModel: 关联嵌入模型\n```\n\n### 在索引过程中的作用\n\n1. **文档编码**：将原始文档分块后，使用嵌入模型编码为向量\n2. **实体编码**：从OpenIE提取的实体编码为向量\n3. **事实编码**：从OpenIE提取的事实三元组编码为向量\n4. **KNN检索**：基于向量相似度构建知识图谱的同义词边\n\n资料来源：[src/hipporag/HippoRAG.py:1-50]()\n\n## 依赖组件\n\n### Python包依赖\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `torch` | 2.5.1 | 张量计算和CUDA支持 |\n| `transformers` | 4.45.2 | 模型加载和推理 |\n| `sentence-transformers` | - | SentenceTransformer模型支持 |\n| `gritlm` | 1.0.2 | GritLM模型支持 |\n| `vllm` | 0.6.6.post1 | vLLM服务端支持 |\n| `numpy` | - | 向量数据处理 |\n\n资料来源：[setup.py:1-30]()\n\n## 扩展开发\n\n### 添加新的嵌入模型\n\n1. 继承 `BaseEmbeddingModel` 基类\n2. 实现 `encode()` 方法\n3. 在 `__init__.py` 的 `get_embedding_model()` 中添加模型选择逻辑\n\n```python\n# src/hipporag/embedding_model/CustomModel.py\nfrom .base import BaseEmbeddingModel\n\nclass CustomEmbeddingModel(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name\n # 初始化自定义模型\n \n def encode(self, texts):\n # 实现编码逻辑\n pass\n```\n\n```python\n# src/hipporag/embedding_model/__init__.py\ndef get_embedding_model(global_config, embedding_model_name):\n if embedding_model_name.startswith(\"CustomModel/\"):\n return CustomEmbeddingModel(global_config, embedding_model_name)\n # ... 其他模型\n```\n\n## 性能优化建议\n\n| 优化项 | 说明 |\n|--------|------|\n| 批处理大小 | 根据GPU显存调整 `embedding_batch_size`，默认16 |\n| 序列长度 | 确保 `embedding_max_seq_len` 匹配模型能力 |\n| 归一化 | 启用 `embedding_return_as_normalized=True` 可加速相似度计算 |\n| 混合部署 | 将嵌入模型与LLM部署在不同GPU上避免显存竞争 |\n\n资料来源：[README.md - Quick Start]()\n\n---\n\n\n\n## OpenIE信息抽取\n\n### 相关页面\n\n相关主题：[知识图谱构建](#p4), [Prompt模板管理](#p8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/information_extraction/openie_openai_gpt.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/information_extraction/openie_openai_gpt.py)\n- [src/hipporag/information_extraction/openie_vllm_offline.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/information_extraction/openie_vllm_offline.py)\n- [src/hipporag/information_extraction/openie_transformers_offline.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/information_extraction/openie_transformers_offline.py)\n- [src/hipporag/prompts/templates/triple_extraction.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/prompts/templates/triple_extraction.py)\n- [src/hipporag/prompts/templates/ner.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/prompts/templates/ner.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n \n\n# OpenIE信息抽取\n\n## 概述\n\nOpenIE（Open Information Extraction，开放信息抽取）是HippoRAG框架中的核心组件，负责从文本语料中自动提取结构化的知识三元组。这些三元组构成了HippoRAG知识图谱的基础节点和边，使得大型语言模型能够识别和利用文档之间的语义关联，从而显著提升检索增强生成（RAG）的效果。\n\n在HippoRAG系统中，OpenIE信息抽取的主要职责包括：\n\n- **三元组抽取**：从原始文本中提取形如`(主语, 谓词, 宾语)`的结构化知识表示\n- **实体识别**：识别文本中的命名实体及其类型\n- **知识图谱构建**：为后续的图检索和个性化PageRank算法提供基础结构\n\nHippoRAG支持多种OpenIE运行模式，开发者可根据实际需求选择使用在线API（如OpenAI GPT）或离线部署（如vLLM、Transformers）的方式进行信息抽取。资料来源：[src/hipporag/utils/config_utils.py:28-35]()\n\n## 架构设计\n\n### 组件结构\n\nHippoRAG的OpenIE信息抽取模块采用模块化设计，主要包含以下核心组件：\n\n```mermaid\ngraph TD\n A[文本输入] --> B[文本预处理]\n B --> C[OpenIE信息抽取模块]\n C --> D{运行模式选择}\n D -->|online| E[OpenAI GPT抽取器]\n D -->|offline| F[vLLM离线抽取器]\n D -->|Transformers-offline| G[Transformers离线抽取器]\n E --> H[三元组输出]\n F --> H\n G --> H\n H --> I[知识图谱构建]\n```\n\n### 文件组织\n\n```\nsrc/hipporag/\n├── information_extraction/ # OpenIE信息抽取模块\n│ ├── __init__.py # 模块初始化与导出\n│ ├── base.py # 基类定义\n│ ├── openie_openai_gpt.py # OpenAI GPT在线抽取实现\n│ ├── openie_vllm_offline.py # vLLM离线批量抽取实现\n│ └── openie_transformers_offline.py # Transformers离线抽取实现\n└── prompts/\n └── templates/\n ├── triple_extraction.py # 三元组抽取提示模板\n └── ner.py # 命名实体识别提示模板\n```\n\n## 运行模式\n\nHippoRAG的OpenIE模块支持三种运行模式，通过配置参数`openie_mode`进行选择：\n\n| 模式 | 配置值 | 描述 | 适用场景 |\n|------|--------|------|----------|\n| 在线模式 | `online` | 使用OpenAI GPT API进行实时抽取 | 快速原型开发、小规模数据集 |\n| vLLM离线模式 | `offline` | 使用本地部署的vLLM服务进行批量抽取 | 大规模生产环境、降低成本 |\n| Transformers离线模式 | `Transformers-offline` | 使用本地Transformers模型进行抽取 | 完全离线环境、特定模型需求 |\n\n### 在线模式（OpenAI GPT）\n\n在线模式使用OpenAI GPT模型进行信息抽取，是默认的运行模式。该模式配置简单，适合快速验证和小型数据集场景。\n\n```python\n# 配置示例\nconfig = BaseConfig(\n openie_mode='online',\n information_extraction_model_name='openie_openai_gpt'\n)\n```\n\n主要特点：\n\n- 配置简便，无需本地部署模型\n- 依赖OpenAI API，需要有效的API密钥\n- 适合开发和测试阶段\n- 支持的模型：`gpt-4o`、`gpt-4o-mini`等\n\n资料来源：[src/hipporag/utils/config_utils.py:28-35]()\n\n### vLLM离线模式\n\nvLLM离线模式使用本地部署的vLLM推理服务进行批量信息抽取，是生产环境推荐的方式。\n\n```python\n# 配置示例\nconfig = BaseConfig(\n openie_mode='offline',\n information_extraction_model_name='openie_openai_gpt' # 使用OpenIE格式\n)\n```\n\n**部署要求：**\n\n```bash\n# 启动vLLM服务\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nvllm serve meta-llama/Llama-3.3-70B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n主要优势：\n\n- **成本效益**：无需支付API调用费用\n- **性能优化**：支持张量并行，加速批量处理\n- **隐私保护**：数据完全在本地处理\n- **可扩展性**：支持更大规模的语料处理\n\n资料来源：[README.md - Local Deployment (vLLM)]()\n\n### Transformers离线模式\n\n该模式使用HuggingFace Transformers库直接加载模型进行推理，适合完全离线或需要使用特定模型的场景。\n\n```python\n# 配置示例\nconfig = BaseConfig(\n openie_mode='Transformers-offline',\n information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct'\n)\n```\n\n使用示例（来自`test_transformers.py`）：\n\n```python\nglobal_config = BaseConfig(\n openie_mode='Transformers-offline',\n information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct'\n)\n\nhipporag = HippoRAG(\n global_config,\n save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name,\n)\n```\n\n## 抽取流程\n\n### 整体工作流\n\n```mermaid\ngraph LR\n A[文档集合] --> B[文档分块
Chunking]\n B --> C[分块文本]\n C --> D{openie_mode}\n D -->|online| E[调用OpenAI API]\n D -->|offline| F[调用vLLM服务]\n D -->|Transformers| G[本地模型推理]\n E --> H[三元组解析]\n F --> H\n G --> H\n H --> I[结果存储]\n I --> J[知识图谱构建]\n```\n\n### 三元组抽取\n\n三元组抽取是OpenIE的核心功能，将非结构化文本转换为`(主语, 谓词, 宾语)`形式的知识表示。\n\n**抽取提示模板**（`triple_extraction.py`）：\n\n系统使用精心设计的提示模板引导语言模型输出结构化的三元组信息。提示模板通常包含：\n\n- 抽取任务的明确定义\n- 输出格式规范（如JSON格式）\n- 示例输入输出对\n- 边界情况处理指南\n\n**输出格式示例：**\n\n```json\n[\n {\n \"subject\": \"Oliver Badman\",\n \"predicate\": \"is a\",\n \"object\": \"politician\"\n },\n {\n \"subject\": \"The prince\",\n \"predicate\": \"used\",\n \"object\": \"the lost glass slipper\"\n }\n]\n```\n\n### 命名实体识别\n\nNER模块（`ner.py`）负责识别文本中的命名实体，包括人名、地点、组织等。识别的实体用于：\n\n- 增强知识图谱的节点信息\n- 辅助实体链接和消歧\n- 提供更丰富的检索特征\n\n## 配置参数\n\n### 全局配置项\n\nHippoRAG的`BaseConfig`类提供了丰富的OpenIE相关配置选项：\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `information_extraction_model_name` | Literal | `openie_openai_gpt` | 信息抽取模型类名 |\n| `openie_mode` | Literal | `online` | OpenIE运行模式：`online`、`offline`或`Transformers-offline` |\n| `skip_graph` | bool | `False` | 是否跳过图构建（首次离线索引时设为True） |\n| `save_openie` | bool | `True` | 是否保存OpenIE结果到磁盘 |\n\n### 高级配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `preprocess_encoder_name` | str | `gpt-4o` | 预处理编码器名称（用于文档分块） |\n| `preprocess_chunk_max_token_size` | int | `None` | 每个chunk的最大token数，`None`表示整个文档作为单一chunk |\n| `preprocess_chunk_overlap_token_size` | int | `128` | 相邻chunk之间的重叠token数 |\n\n资料来源：[src/hipporag/utils/config_utils.py:28-72]()\n\n## 使用指南\n\n### 快速开始\n\n#### 1. 环境配置\n\n```bash\n# 设置环境变量\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=\n\n# 激活环境\nconda activate hipporag\n```\n\n#### 2. 基础使用示例\n\n```python\nfrom hipporag import HippoRAG\n\n# 准备文档\ndocs = [\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"\n]\n\n# 初始化HippoRAG\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# 执行索引（包括OpenIE抽取）\nhipporag.index(docs=docs)\n\n# 执行问答检索\nqueries = [\"What is George Rankin's occupation?\"]\ngold_docs = [[\"George Rankin is a politician.\"]]\nanswers = [[\"Politician\"]]\n\nresults = hipporag.rag_qa(\n queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers\n)\n```\n\n### vLLM离线模式完整流程\n\n#### 步骤1：启动vLLM服务\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nvllm serve meta-llama/Llama-3.3-70B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n#### 步骤2：运行主程序\n\n```bash\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=''\n\npython main.py \\\n --dataset sample \\\n --llm_name meta-llama/Llama-3.3-70B-Instruct \\\n --openie_mode offline \\\n --skip_graph\n```\n\n#### 步骤3：完成索引和问答\n\n首次运行使用`--skip_graph`参数后，OpenIE结果会保存到文件。第二次运行时去掉该参数即可完成图构建：\n\n```bash\npython main.py \\\n --dataset sample \\\n --llm_name meta-llama/Llama-3.3-70B-Instruct \\\n --openie_mode offline\n```\n\n资料来源：[README.md - Reproducing our Experiments]()\n\n### 调试技巧\n\n1. **使用小数据集调试**：项目提供的`/reproduce/dataset/sample.json`是专门用于调试的小数据集\n\n2. **清理缓存**：重新运行实验时，记得清除保存的文件：\n ```bash\n rm reproduce/dataset/openie_results/openie_sample_results_*.json\n rm -rf outputs/sample/\n ```\n\n3. **vLLM离线模式调试**：当遇到问题时，将`hipporag/llm/vllm_offline.py`中的`tensor_parallel_size`设为1\n\n4. **查看保存的OpenIE结果**：OpenIE结果默认保存，可直接检查输出格式是否正确\n\n## 输出与存储\n\n### OpenIE结果保存\n\nOpenIE抽取结果默认保存到指定目录，文件命名格式包含模型和数据集信息：\n\n```\noutputs//_/openie_results/\n└── openie__results_.json\n```\n\n### 结果格式\n\n```json\n{\n \"doc_id\": 0,\n \"doc_text\": \"Oliver Badman is a politician.\",\n \"triples\": [\n {\n \"subject\": \"Oliver Badman\",\n \"predicate\": \"is a\",\n \"object\": \"politician\"\n }\n ],\n \"entities\": [\n {\"text\": \"Oliver Badman\", \"type\": \"PERSON\"}\n ]\n}\n```\n\n### 与知识图谱的集成\n\nOpenIE抽取的三元组直接用于构建HippoRAG的知识图谱：\n\n```mermaid\ngraph LR\n A[三元组] --> B[实体节点]\n A --> C[关系边]\n B --> D[知识图谱]\n C --> D\n D --> E[个性化PageRank检索]\n E --> F[LLM问答生成]\n```\n\n## 性能优化建议\n\n### 1. 批量处理\n\n离线模式支持批量调用，可显著提升处理速度：\n\n```python\n# 批量文档索引\nhipporag.index(docs=large_documents_list)\n```\n\n### 2. GPU资源分配\n\n- **vLLM服务**：分配专用GPU（如0,1）\n- **主程序**：使用另一组GPU（如2,3）\n- 通过`CUDA_VISIBLE_DEVICES`环境变量控制\n\n### 3. 内存优化\n\n```bash\n# 调整最大序列长度\n--max_model_len 4096\n\n# 调整GPU内存利用率\n--gpu-memory-utilization 0.95\n```\n\n### 4. 并行配置\n\n```bash\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\n```\n\n## 常见问题\n\n### Q1: 首次运行vLLM离线模式需要设置什么参数？\n\n需要设置`--skip_graph`参数，因为首次运行时图尚未构建：\n\n```bash\npython main.py --openie_mode offline --skip_graph\n```\n\n### Q2: 如何切换不同的OpenIE模型？\n\n通过修改`information_extraction_model_name`配置：\n\n```python\n# 使用OpenAI GPT\nconfig = BaseConfig(information_extraction_model_name='openie_openai_gpt')\n\n# 使用Transformers模型\nconfig = BaseConfig(\n information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct',\n openie_mode='Transformers-offline'\n)\n```\n\n### Q3: OpenIE结果支持增量更新吗？\n\n是的，HippoRAG支持增量更新。删除文档后重新索引，已保存的OpenIE结果会被重用。\n\n### Q4: 如何处理长文档？\n\n对于过长的文档，建议先进行分块处理：\n\n```python\nconfig = BaseConfig(\n preprocess_chunk_max_token_size=512,\n preprocess_chunk_overlap_token_size=64\n)\n```\n\n## 参考链接\n\n- HippoRAG官方仓库：https://github.com/OSU-NLP-Group/HippoRAG\n- HippoRAG 2论文：https://arxiv.org/abs/2502.14802\n- HippoRAG 1论文：https://arxiv.org/abs/2405.14831\n- vLLM文档：https://docs.vllm.ai/\n\n---\n\n\n\n## Prompt模板管理\n\n### 相关页面\n\n相关主题：[OpenIE信息抽取](#p7), [LLM模型集成](#p5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/prompts/templates/README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/prompts/templates/README.md)\n- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)\n- [src/hipporag/StandardRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/StandardRAG.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n \n\n# Prompt模板管理\n\n## 概述\n\nHippoRAG框架中的Prompt模板管理模块负责组织和调用系统中各类LLM推理所需的提示词模板。该模块位于 `src/hipporag/prompts/` 目录下，采用模块化的设计思想，将不同功能场景的提示词模板分别存放于独立文件中，便于维护和扩展。\n\nPrompt模板管理系统的核心作用包括：\n\n- **模板存储与加载**：通过文件系统组织提示词模板，支持动态加载\n- **模板渲染**：使用 `prompt_template_manager` 将占位符替换为实际数据\n- **数据集适配**：根据不同数据集选择对应的提示词模板\n- **统一接口**：为HippoRAG和StandardRAG等组件提供一致的模板访问方式\n\n资料来源：[src/hipporag/prompts/templates/README.md:1-18]()\n\n## 目录结构\n\n```\nsrc/hipporag/prompts/\n├── __init__.py\n├── prompt_template_manager.py # 模板管理器核心实现\n├── linking.py # 图谱链接相关提示词\n├── filter_default_prompt.py # 过滤模块默认提示词\n├── templates/\n│ ├── __init__.py\n│ ├── rag_qa_musique.py # MuSiQue数据集QA模板\n│ ├── ircot_hotpotqa.py # HotpotQA多跳问答模板\n│ └── ... # 其他数据集模板\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 模板定义规范\n\n### 文件命名规则\n\n模板文件夹 `templates/` 被作为 `hipporag` 项目下的子模块处理。每个 `*.py` 文件（除 `__init__.py` 外）对应一个提示词模板，文件名（不含文件扩展名）将作为访问该模板的键名。\n\n| 规则 | 说明 |\n|------|------|\n| 文件扩展名 | 必须为 `.py` |\n| 排除文件 | `__init__.py` 不被视为模板 |\n| 命名规范 | 使用下划线连接，如 `rag_qa_musique.py` |\n| 访问键名 | 文件名去掉 `.py` 后缀，如 `rag_qa_musique` |\n\n资料来源：[src/hipporag/prompts/templates/README.md:5-8]()\n\n### 模板变量规范\n\n每个模板文件必须定义一个名为 `prompt_template` 的变量来存储提示词内容。该变量可以是以下三种形式之一：\n\n```python\n# 形式1: 字符串（支持 ${} 占位符）\nprompt_template = \"Question: ${question}\\nAnswer:\"\n\n# 形式2: Template对象实例\nfrom string import Template\nprompt_template = Template(\"Wikipedia Title: ${title}\\n\\n${text}\")\n\n# 形式3: 聊天历史格式（List[dict]）\nprompt_template = [\n {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"},\n {\"role\": \"user\", \"content\": \"Question: ${question}\"}\n]\n```\n\n| 形式 | 数据类型 | 占位符格式 | 适用场景 |\n|------|----------|------------|----------|\n| 字符串 | `str` | `${variable}` | 简单模板 |\n| Template对象 | `Template` | `$variable` 或 `${variable}` | 需要转义的场景 |\n| 聊天历史 | `List[dict]` | `${variable}` | 多轮对话模板 |\n\n资料来源：[src/hipporag/prompts/templates/README.md:10-17]()\n\n## 模板渲染机制\n\n### PromptTemplateManager\n\n`PromptTemplateManager` 是模板系统的核心管理类，负责模板的加载、验证和渲染。\n\n#### 模板选择逻辑\n\nHippoRAG在执行检索和QA任务时，会根据当前数据集选择对应的提示词模板。核心逻辑如下：\n\n```python\nif self.prompt_template_manager.is_template_name_valid(name=f'rag_qa_{self.global_config.dataset}'):\n # 查找该数据集对应的自定义提示词\n prompt_dataset_name = self.global_config.dataset\nelse:\n # 数据集尚未定义自定义模板，使用MuSiQue的通用模板作为后备\n logger.debug(\n f\"rag_qa_{self.global_config.dataset} does not have a customized prompt template. \"\n f\"Using MUSIQUE's prompt template instead.\")\n prompt_dataset_name = 'musique'\n```\n\n资料来源：[src/hipporag/HippoRAG.py:1-20]()\n\n#### 模板渲染流程\n\n```mermaid\ngraph TD\n A[开始渲染] --> B{数据集模板是否存在?}\n B -->|是| C[使用数据集特定模板]\n B -->|否| D[使用musique通用模板]\n C --> E[调用render方法]\n D --> E\n E --> F[替换prompt_user占位符]\n F --> G[返回渲染后的消息]\n```\n\n### 模板渲染示例\n\nHippoRAG在QA阶段将检索到的文档传入模板进行渲染：\n\n```python\nprompt_user = ''\nfor passage in retrieved_passages:\n prompt_user += f'Wikipedia Title: {passage}\\n\\n'\nprompt_user += 'Question: ' + query_solution.question + '\\nThought: '\n\nall_qa_messages.append(\n self.prompt_template_manager.render(\n name=f'rag_qa_{prompt_dataset_name}', \n prompt_user=prompt_user\n )\n)\n```\n\n资料来源：[src/hipporag/HippoRAG.py:1-15]()\n\n## 预置模板\n\n### MuSiQue数据集模板\n\n`rag_qa_musique.py` 是HippoRAG的默认提示词模板，用于多跳问答场景。\n\n```python\nprompt_template = \"\"\"Given the following Wikipedia passages, ...\n\nThought: The question asks about ...\nWe need to find passages about ...\n...\n\nQuestion: {question}\nThought: \"\"\"\n```\n\n该模板采用Chain-of-Thought（思维链）风格，引导LLM逐步推理多跳问题。\n\n资料来源：[src/hipporag/prompts/templates/rag_qa_musique.py]()\n\n### HotpotQA模板\n\n`ircot_hotpotqa.py` 实现基于IRCoT（Iterated Retrieval Chain-of-Thought）的提示词模板，适用于HotpotQA双跳问答数据集。\n\n资料来源：[src/hipporag/prompts/templates/ircot_hotpotqa.py]()\n\n## 配置参数\n\nHippoRAG通过 `BaseConfig` 类管理模板相关的配置参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `dataset` | `str` | `None` | 当前数据集名称，用于选择对应模板 |\n| `max_qa_steps` | `int` | `1` | 单问题最大迭代推理步数 |\n| `qa_top_k` | `int` | `5` | 输入QA模型的文档数量 |\n\n```python\n# QA特定配置\nmax_qa_steps: int = field(\n default=1,\n metadata={\"help\": \"For answering a single question, the max steps that we use to interleave retrieval and reasoning.\"}\n)\nqa_top_k: int = field(\n default=5,\n metadata={\"help\": \"Feeding top k documents to the QA model for reading.\"}\n)\n```\n\n资料来源：[src/hipporag/utils/config_utils.py:1-15]()\n\n## 使用示例\n\n### 基本使用流程\n\n```python\nfrom hipporag import HippoRAG\n\n# 初始化HippoRAG（会自动加载模板管理器）\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# 索引文档\nhipporag.index(docs=documents)\n\n# 执行QA（自动使用对应数据集的模板）\nresults = hipporag.rag_qa(\n queries=questions,\n gold_docs=gold_documents,\n gold_answers=expected_answers\n)\n```\n\n### 自定义模板\n\n如需为新数据集添加模板，需在 `src/hipporag/prompts/templates/` 目录下创建新文件：\n\n1. 创建 `rag_qa_your_dataset.py`\n2. 定义 `prompt_template` 变量\n3. 使用 `${}` 占位符标记需替换的位置\n\n```python\n# rag_qa_your_dataset.py\nprompt_template = \"\"\"Based on the following context...\n\nContext: {prompt_user}\n\nPlease answer the question based on the context.\"\"\"\n```\n\n创建后，系统会自动识别并可使用 `rag_qa_your_dataset` 作为模板名称。\n\n资料来源：[src/hipporag/prompts/templates/README.md:5-12]()\n\n## 与其他模块的集成\n\n### HippoRAG集成\n\n`HippoRAG` 类在执行 `rag_qa` 方法时调用模板管理器：\n\n```python\n# 位置: src/hipporag/HippoRAG.py\nall_qa_messages.append(\n self.prompt_template_manager.render(\n name=f'rag_qa_{prompt_dataset_name}', \n prompt_user=prompt_user\n )\n)\n```\n\n### StandardRAG集成\n\n`StandardRAG` 类使用完全相同的模板管理逻辑：\n\n```python\n# 位置: src/hipporag/StandardRAG.py\nall_qa_messages.append(\n self.prompt_template_manager.render(\n name=f'rag_qa_{prompt_dataset_name}', \n prompt_user=prompt_user\n )\n)\n```\n\n两者的模板选择和渲染机制保持一致，确保不同RAG变体之间的行为统一。\n\n资料来源：[src/hipporag/StandardRAG.py:1-15]()\n\n## 总结\n\nHippoRAG的Prompt模板管理系统具有以下特点：\n\n| 特性 | 描述 |\n|------|------|\n| **模块化设计** | 模板按数据集组织，便于维护和扩展 |\n| **灵活格式** | 支持字符串、Template对象和聊天历史三种格式 |\n| **自动回退** | 未知数据集自动回退到MuSiQue通用模板 |\n| **统一接口** | 为HippoRAG和StandardRAG提供一致的模板访问 |\n| **易于扩展** | 仅需创建新的 `.py` 文件即可添加模板 |\n\n该设计使得HippoRAG能够优雅地处理不同数据集的提示词需求，同时保持代码的简洁性和可维护性。\n\n---\n\n\n\n## 实验复现指南\n\n### 相关页面\n\n相关主题：[快速入门指南](#p2), [评估与测试](#p10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [main_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_azure.py)\n- [main_dpr.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_dpr.py)\n- [reproduce/README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/reproduce/README.md)\n- [reproduce/dataset/sample_corpus.json](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/reproduce/dataset/sample_corpus.json)\n \n\n# 实验复现指南\n\n本页面详细说明如何基于 HippoRAG 仓库复现论文中的实验结果。指南涵盖环境配置、数据准备、索引构建、检索与问答等完整流程。\n\n## 1. 环境准备\n\n### 1.1 系统要求\n\nHippoRAG 对运行环境有明确的依赖要求，需确保满足以下条件：\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | >= 3.10 | 必须使用 Python 3.10 或更高版本 |\n| CUDA | 兼容 | 需要 GPU 支持进行模型推理 |\n| GPU 显存 | 视模型而定 | 建议多卡以支持大型模型 |\n\n### 1.2 依赖安装\n\n首先创建独立的 conda 环境并安装核心依赖：\n\n```bash\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install hipporag\n```\n\n资料来源：[README.md:1]()\n\n### 1.3 环境变量配置\n\n启动 HippoRAG 前需配置以下环境变量：\n\n```bash\n# GPU 配置\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\n\n# HuggingFace 模型缓存路径\nexport HF_HOME=\n\n# OpenAI API 密钥（使用 OpenAI 模型时必需）\nexport OPENAI_API_KEY=\n\n# 激活环境\nconda activate hipporag\n```\n\n资料来源：[README.md:1]()\n\n### 1.4 vLLM 本地部署环境\n\n如需使用本地 vLLM 部署，需额外配置：\n\n```bash\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n```\n\n## 2. 数据准备\n\n### 2.1 数据集来源\n\n实验所需数据集可从以下渠道获取：\n\n| 数据集类型 | 来源 | 说明 |\n|------------|------|------|\n| 预定义数据集 | `reproduce/dataset/` 目录 | 仓库已包含部分采样数据集 |\n| 完整数据集 | [HuggingFace HippoRAG_v2](https://huggingface.co/datasets/osunlp/HippoRAG_v2) | 包含完整的评估数据集 |\n| OpenIE 结果 | `outputs/musique/` 目录 | 已预处理的信息抽取结果 |\n\n资料来源：[README.md:1]()\n\n### 2.2 数据目录结构\n\n推荐将数据集统一放置在 `reproduce/dataset/` 目录下：\n\n```\nreproduce/\n└── dataset/\n ├── sample_corpus.json # 语料库文件\n ├── sample.json # 查询文件（含答案）\n └── _corpus.json\n```\n\n### 2.3 语料库 JSON 格式\n\n语料库文件需遵循特定的 JSON 数组格式：\n\n```json\n[\n {\n \"title\": \"FIRST PASSAGE TITLE\",\n \"text\": \"FIRST PASSAGE TEXT\",\n \"idx\": 0\n },\n {\n \"title\": \"SECOND PASSAGE TITLE\",\n \"text\": \"SECOND PASSAGE TEXT\",\n \"idx\": 1\n }\n]\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| title | string | 是 | 段落标题 |\n| text | string | 是 | 段落正文内容 |\n| idx | integer | 是 | 段落唯一索引 |\n\n资料来源：[reproduce/README.md]()\n\n### 2.4 查询 JSON 格式（可选）\n\n如需进行评估，需准备包含问题和标准答案的查询文件：\n\n```json\n[\n {\n \"id\": \"sample/question_1.json\",\n \"question\": \"QUESTION\",\n \"answer\": [\"ANSWER\"],\n \"answerable\": true,\n \"paragraphs\": [\n {\n \"title\": \"{FIRST SUPPORTING PASSAGE TITLE}\",\n \"text\": \"{FIRST SUPPORTING PASSAGE TEXT}\",\n \"is_supporting\": true,\n \"idx\": 0\n }\n ]\n }\n]\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| id | string | 是 | 问题唯一标识 |\n| question | string | 是 | 查询问题文本 |\n| answer | array | 是 | 标准答案列表 |\n| answerable | boolean | 是 | 问题是否可答 |\n| paragraphs | array | 是 | 支持段落列表 |\n\n### 2.5 长文本分块\n\n对于过长的段落，可能需要在 OpenIE 处理前进行分块：\n\n> 当准备数据时，可能需要对每个段落进行分块，因为较长的段落可能对 OpenIE 过程过于复杂。\n\n资料来源：[README.md:1]()\n\n## 3. 实验运行流程\n\n### 3.1 整体工作流\n\n```mermaid\ngraph TD\n A[准备数据集] --> B[配置环境变量]\n B --> C{选择模型部署方式}\n C -->|OpenAI| D[设置 API 配置]\n C -->|vLLM 本地| E[启动 vLLM 服务]\n D --> F[运行 main.py]\n E --> G[运行 main.py]\n F --> H[索引构建]\n G --> H\n H --> I[检索与问答]\n I --> J[输出评估结果]\n```\n\n### 3.2 命令行参数说明\n\n`main.py` 支持多种命令行参数配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| --dataset | string | 必需 | 数据集名称 |\n| --llm_name | string | 必需 | LLM 模型名称 |\n| --llm_base_url | string | 必需 | LLM API 端点 |\n| --embedding_name | string | 必需 | 嵌入模型名称 |\n| --openie_mode | string | 'gpt-4o-mini' | OpenIE 运行模式 |\n\n资料来源：[main.py:1]()\n\n### 3.3 配置类参数\n\nHippoRAG 使用 `BaseConfig` 类管理核心配置参数：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| graph_type | 图类型 | facts_and_sim_passage_node_unidirectional |\n| embedding_batch_size | 嵌入批处理大小 | 8 |\n| max_new_tokens | 最大生成 token 数 | None |\n| retrieval_top_k | 检索返回文档数 | 200 |\n| linking_top_k | 每步链接节点数 | 5 |\n| max_qa_steps | QA 最大推理步数 | 3 |\n| qa_top_k | QA 输入 top k 文档数 | 5 |\n| damping | PPR 算法阻尼因子 | 0.5 |\n\n资料来源：[src/hipporag/utils/config_utils.py:1]()\n\n## 4. 使用 OpenAI 模型\n\n### 4.1 快速启动流程\n\n使用 OpenAI 模型进行实验的标准流程：\n\n```bash\n# 设置数据集\ndataset=sample # 或其他数据集\n\n# 运行 OpenAI 模型\npython main.py \\\n --dataset $dataset \\\n --llm_base_url https://api.openai.com/v1 \\\n --llm_name gpt-4o-mini \\\n --embedding_name nvidia/NV-Embed-v2\n```\n\n资料来源：[README.md:1]()\n\n### 4.2 支持的 OpenAI 兼容模型\n\nHippoRAG 支持任何 OpenAI 兼容的 API 端点，包括：\n\n- GPT-4 系列模型\n- GPT-3.5 系列模型\n- Azure OpenAI 部署模型\n- 其他 OpenAI 兼容的第三方 API\n\n### 4.3 Azure OpenAI 部署\n\n使用 Azure 端点时需指定额外参数：\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name,\n azure_endpoint=\"https://[ENDPOINT NAME].openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2025-01-01-preview\",\n azure_embedding_endpoint=\"https://[ENDPOINT NAME].openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2023-05-15\"\n)\n```\n\n资料来源：[main_azure.py:1]()\n\n## 5. 使用 vLLM 本地部署\n\n### 5.1 vLLM 服务启动\n\nvLLM 提供了 OpenAI 兼容的本地推理服务，启动步骤如下：\n\n```bash\n# 使用指定 GPU 启动服务（留足显存给嵌入模型）\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\n# 启动模型服务\nvllm serve meta-llama/Llama-3.3-70B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n**参数调整建议：**\n\n| 参数 | 说明 | 调整建议 |\n|------|------|----------|\n| tensor-parallel-size | 并行 GPU 数量 | 根据可用 GPU 调整 |\n| max_model_len | 最大模型上下文长度 | 根据显存调整，显存不足时减小 |\n| gpu-memory-utilization | GPU 显存利用率 | 默认为 0.95，OOM 时减小 |\n\n资料来源：[README.md:1]()\n\n### 5.2 运行主程序\n\nvLLM 服务启动后，使用另一组 GPU 运行主程序：\n\n```bash\n# 设置另一组 GPU\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\n\n# 运行实验\npython main.py \\\n --dataset $dataset \\\n --llm_base_url http://localhost:6578/v1 \\\n --llm_name meta-llama/Llama-3.3-70B-Instruct \\\n --embedding_name nvidia/NV-Embed-v2\n```\n\n资料来源：[README.md:1]()\n\n### 5.3 轻量级测试配置\n\n为节省测试成本，可使用较小的模型：\n\n```bash\n# 测试用 vLLM 启动\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n\n# 运行本地测试\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:1]()\n\n## 6. 测试验证\n\n### 6.1 OpenAI 模型测试\n\n验证环境配置正确性的快速测试：\n\n```bash\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n该测试成本可忽略不计，可用于验证基本功能。\n\n### 6.2 本地模型测试\n\n使用本地部署模型进行完整功能测试：\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\n# 启动 vLLM 服务后\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n### 6.3 测试覆盖范围\n\n测试脚本验证以下核心模块功能：\n\n- 索引构建（Indexing）\n- 图加载（Graph Loading）\n- 文档删除（Document Deletion）\n- 增量更新（Incremental Updates）\n\n资料来源：[README.md:1]()\n\n## 7. 完整示例代码\n\n### 7.1 基本使用流程\n\n以下代码展示了完整的 HippoRAG 使用流程：\n\n```python\nfrom hipporag import HippoRAG\n\n# 初始化配置\nsave_dir = 'outputs'\nllm_model_name = 'gpt-4o-mini'\nembedding_model_name = 'nvidia/NV-Embed-v2'\n\n# 创建实例\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name\n)\n\n# 索引文档\ndocs = [\"文档内容1\", \"文档内容2\", \"文档内容3\"]\nhipporag.index(docs=docs)\n\n# 执行检索与问答\nqueries = [\"查询问题1\", \"查询问题2\"]\ngold_docs = [[\"相关文档1\"], [\"相关文档2\"]]\nanswers = [[\"答案1\"], [\"答案2\"]]\n\nresults = hipporag.rag_qa(\n queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers\n)\n```\n\n### 7.2 OpenAI 兼容端点\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='Your LLM Model name',\n llm_base_url='Your LLM Model url',\n embedding_model_name='Your Embedding model name',\n embedding_base_url='Your Embedding model url'\n)\n```\n\n### 7.3 main.py 核心逻辑\n\n```python\ndef main():\n args = parse_args()\n \n # 加载数据集\n corpus, all_queries, gold_docs, gold_answers = load_data(args.dataset)\n \n # 配置参数\n config = BaseConfig(\n dataset=args.dataset,\n openie_mode=args.openie_mode,\n information_extraction_model_name=args.llm_name,\n retrieval_top_k=200,\n linking_top_k=5,\n max_qa_steps=3,\n qa_top_k=5,\n graph_type=\"facts_and_sim_passage_node_unidirectional\",\n embedding_batch_size=8,\n corpus_len=len(corpus)\n )\n \n # 初始化并运行\n hipporag = HippoRAG(global_config=config)\n hipporag.index(corpus)\n hipporag.rag_qa(\n queries=all_queries,\n gold_docs=gold_docs,\n gold_answers=gold_answers\n )\n```\n\n资料来源：[main.py:1]()\n\n## 8. 常见问题排查\n\n### 8.1 GPU 显存不足 (OOM)\n\n**解决方案：**\n\n1. 减小 `gpu-memory-utilization` 参数（建议从 0.95 逐步降低）\n2. 减小 `max_model_len` 参数\n3. 增加 `tensor-parallel-size` 以分散显存占用\n\n### 8.2 OpenAI API 调用失败\n\n**检查项：**\n\n1. 确认 `OPENAI_API_KEY` 环境变量已正确设置\n2. 验证 API 端点 URL 格式正确\n3. 检查网络连接和代理设置\n\n### 8.3 vLLM 服务无响应\n\n**排查步骤：**\n\n1. 确认 vLLM 服务进程正在运行\n2. 检查端口 6578 是否被占用\n3. 验证 GPU 可见性配置正确\n\n## 9. 参考链接\n\n| 资源 | 链接 |\n|------|------|\n| HippoRAG 2 论文 | [arXiv:2502.14802](https://arxiv.org/abs/2502.14802) |\n| HippoRAG 1 论文 | [arXiv:2405.14831](https://arxiv.org/abs/2405.14831) |\n| HuggingFace 数据集 | [osunlp/HippoRAG_v2](https://huggingface.co/datasets/osunlp/HippoRAG_v2) |\n| vLLM 文档 | [docs.vllm.ai](https://docs.vllm.ai/en/latest/getting_started/quickstart.html) |\n| GitHub 仓库 | [OSU-NLP-Group/HippoRAG](https://github.com/OSU-NLP-Group/HippoRAG) |\n\n---\n\n\n\n## 评估与测试\n\n### 相关页面\n\n相关主题：[实验复现指南](#p9), [Prompt模板管理](#p8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/evaluation/qa_eval.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/qa_eval.py)\n- [src/hipporag/evaluation/retrieval_eval.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/retrieval_eval.py)\n- [src/hipporag/evaluation/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/base.py)\n- [tests_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)\n- [tests_local.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_local.py)\n- [tests_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_azure.py)\n \n\n# 评估与测试\n\n## 概述\n\nHippoRAG 提供了完整的评估与测试框架，用于验证系统的索引构建、检索质量和问答能力。评估模块位于 `src/hipporag/evaluation/` 目录下，分为问答评估（QA Evaluation）和检索评估（Retrieval Evaluation）两个核心组件。资料来源：[README.md:代码结构]()\n\n该框架支持多种部署方式的测试，包括 OpenAI API、Azure OpenAI Service 和本地 vLLM 部署。通过统一的测试接口，开发者可以验证核心模块的功能完整性，包括索引构建、图加载、文档删除和增量更新等关键能力。\n\n---\n\n## 评估模块架构\n\n### 模块结构\n\nHippoRAG 的评估系统采用分层设计，包含基础评估类和具体评估实现。\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 基础评估类 | `src/hipporag/evaluation/base.py` | 定义 `BaseMetric` 基类，供所有评估指标继承 |\n| 问答评估 | `src/hipporag/evaluation/qa_eval.py` | 实现问答任务的评估指标 |\n| 检索评估 | `src/hipporag/evaluation/retrieval_eval.py` | 实现检索任务的评估指标 |\n\n资料来源：[README.md:代码结构]()\n\n### 评估流程\n\n```mermaid\ngraph TD\n A[输入查询] --> B[检索阶段]\n B --> C[文档排序]\n C --> D[Top-K 文档]\n D --> E[QA 模型回答]\n E --> F[评估结果]\n \n G[黄金标准] --> F\n D --> G\n E --> G\n```\n\n评估系统通过对比系统输出与黄金标准（gold standard）来计算性能指标。在 `rag_qa` 方法中，系统接收查询、黄金文档和黄金答案，并返回包含评估指标的完整结果。资料来源：[tests_openai.py:测试流程]()\n\n---\n\n## 核心评估指标\n\n### 问答评估（QA Evaluation）\n\n问答评估模块负责衡量 HippoRAG 生成答案的质量。评估过程接收以下输入参数：\n\n| 参数名 | 类型 | 描述 |\n|--------|------|------|\n| queries | List[str] | 查询问题列表 |\n| gold_docs | List[List[str]] | 每个查询对应的黄金文档 |\n| gold_answers | List[List[str]] | 每个查询对应的黄金答案 |\n\n资料来源：[tests_openai.py:评估参数]()\n\n```python\n# 典型评估调用示例\nanswers = [\n [\"Politician\"], # 黄金答案\n [\"By going to the ball.\"],\n [\"Rockland County\"]\n]\n\ngold_docs = [\n [\"George Rankin is a politician.\"],\n [\"Cinderella attended the royal ball.\",\n \"The prince used the lost glass slipper...\"],\n [\"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"]\n]\n\nresult = hipporag.rag_qa(queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers)\n```\n\n### 检索评估（Retrieval Evaluation）\n\n检索评估模块衡量文档检索的准确性和相关性。该模块评估系统是否能正确识别与查询相关的文档，支持多跳推理场景下的关联检索评估。\n\n---\n\n## 测试框架\n\n### 测试类型概览\n\nHippoRAG 提供了三种测试方式以适应不同的部署环境：\n\n| 测试类型 | 测试文件 | 适用场景 |\n|----------|----------|----------|\n| OpenAI 测试 | `tests_openai.py` | 使用 OpenAI API 进行测试 |\n| 本地测试 | `tests_local.py` | 使用本地 vLLM 部署进行测试 |\n| Azure 测试 | `tests_azure.py` | 使用 Azure OpenAI Service 进行测试 |\n\n资料来源：[README.md:Testing](), [tests_openai.py](), [tests_local.py]()\n\n### 测试环境配置\n\n#### OpenAI 测试\n\nOpenAI 测试是最简单的方式，无需本地部署 LLM。只需配置 API 密钥即可运行：\n\n```bash\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n资料来源：[README.md:OpenAI Test]()\n\n#### 本地测试（vLLM）\n\n本地测试需要先部署 vLLM 服务器，然后运行测试脚本：\n\n```bash\n# 步骤 1：部署 vLLM 服务器\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n\n# 步骤 2：运行测试\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:Local Test]()\n\n#### Azure 测试\n\nAzure 测试使用 Azure OpenAI Service 的部署端点进行测试，配置方式如下：\n\n```python\nhipporag = HippoRAG(save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name,\n azure_endpoint=\"https://[ENDPOINT].openai.azure.com/...\",\n azure_embedding_endpoint=\"https://[ENDPOINT].openai.azure.com/...\")\n```\n\n### 测试覆盖范围\n\nHippoRAG 的测试套件覆盖以下核心功能：\n\n| 测试场景 | 描述 |\n|----------|------|\n| 索引构建 | 验证文档索引的完整性和正确性 |\n| 图加载 | 验证知识图谱的加载和解析 |\n| 文档删除 | 验证从索引中删除文档的功能 |\n| 增量更新 | 验证向现有索引添加新文档的能力 |\n\n资料来源：[README.md:Testing]()\n\n### 测试执行流程\n\n```mermaid\ngraph LR\n A[准备测试数据] --> B[初始化 HippoRAG]\n B --> C[执行索引构建]\n C --> D[运行 RAG QA]\n D --> E[验证评估结果]\n E --> F{测试通过?}\n F -->|是| G[输出结果]\n F -->|否| H[报告错误]\n```\n\n---\n\n## HippoRAG 类测试方法\n\n### 主要测试方法\n\nHippoRAG 类提供了 `rag_qa` 方法用于执行检索增强问答并返回评估结果：\n\n```python\ndef rag_qa(queries: List[str],\n gold_docs: List[List[str]],\n gold_answers: List[List[str]]) -> Any\n```\n\n返回值包含评估指标和系统输出，可通过切片 `[-2:]` 获取最终的评估结果。\n\n资料来源：[tests_openai.py:rag_qa调用](), [tests_local.py:rag_qa调用]()\n\n### 端到端测试示例\n\n以下是一个完整的端到端测试流程：\n\n```python\nfrom hipporag import HippoRAG\n\n# 初始化配置\nsave_dir = 'outputs'\nllm_model_name = 'gpt-4o-mini'\nembedding_model_name = 'nvidia/NV-Embed-v2'\n\n# 创建实例\nhipporag = HippoRAG(save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name)\n\n# 测试数据\ndocs = [\n \"George Rankin is a politician.\",\n \"Cinderella attended the royal ball.\",\n \"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"\n]\n\n# 执行索引\nhipporag.index(docs=docs)\n\n# 执行评估\nqueries = [\"What is George Rankin's occupation?\"]\nanswers = [[\"Politician\"]]\ngold_docs = [[\"George Rankin is a politician.\"]]\n\nresult = hipporag.rag_qa(queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers)\n\nprint(result[-2:])\n```\n\n---\n\n## 配置参数\n\n### 全局配置（BaseConfig）\n\n评估相关的配置参数位于 `BaseConfig` 类中：\n\n| 参数名 | 默认值 | 描述 |\n|--------|--------|------|\n| retrieval_top_k | 200 | 每步检索的文档数量 |\n| linking_top_k | 5 | 每个检索步骤的链接节点数 |\n| max_qa_steps | 3 | 问答最大迭代步数 |\n| qa_top_k | 5 | 输入 QA 模型的顶部文档数 |\n| damping | 0.5 | PPR 算法的阻尼因子 |\n| graph_type | facts_and_sim_passage_node_unidirectional | 图结构类型 |\n\n资料来源：[src/hipporag/utils/config_utils.py:配置参数]()\n\n---\n\n## 最佳实践\n\n### 测试建议\n\n1. **环境验证**：首次使用前，使用 `sample` 数据集进行环境验证\n2. **成本控制**：开发测试优先使用 OpenAI 测试，成本最低\n3. **模型选择**：本地测试推荐使用较小的 8B 模型（如 Llama-3.1-8B-Instruct）以节省 GPU 内存\n4. **资源调优**：如遇 GPU 内存溢出，可调整 `gpu-memory-utilization` 或 `max_model_len` 参数\n\n### 调试建议\n\n测试失败时，按以下顺序排查：\n\n1. 确认 API 密钥或本地服务是否正常\n2. 检查数据集格式是否符合规范（JSON 结构）\n3. 验证环境变量配置是否正确\n4. 检查 GPU 内存是否充足\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：OSU-NLP-Group/HippoRAG\n\n摘要：发现 18 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：add_fact_edges function adds the same edge twice?。\n\n## 1. 安装坑 · 来源证据：add_fact_edges function adds the same edge twice?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：add_fact_edges function adds the same edge twice?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6c7ca8232561460290f1ad50663233af | https://github.com/OSU-NLP-Group/HippoRAG/issues/174 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：pypi hipporag libraries\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：pypi hipporag libraries\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0da5afa434114138a3c745efba4c9ded | https://github.com/OSU-NLP-Group/HippoRAG/issues/168 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an extremely long time. Is this normal?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_90b68b1be49048efba510bfd10623d41 | https://github.com/OSU-NLP-Group/HippoRAG/issues/173 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：OpenAI version incompatibility in latest 2.0.0a4 version\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OpenAI version incompatibility in latest 2.0.0a4 version\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f6679eb5cf884eb9a2d003b39da93c8d | https://github.com/OSU-NLP-Group/HippoRAG/issues/140 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Windows Compatibility Issues with vLLM dependency\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows Compatibility Issues with vLLM dependency\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57d57b9365f342db9a5e8ed48727e99e | https://github.com/OSU-NLP-Group/HippoRAG/issues/117 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：How to use local embedding_model_\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：How to use local embedding_model_\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dd0e2350e55240b3ab754359ca93cb11 | https://github.com/OSU-NLP-Group/HippoRAG/issues/127 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b735fa4a09f942db8f1825092ef8e368 | https://github.com/OSU-NLP-Group/HippoRAG/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：How to distinguish Hipporag1 from Hipporag2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to distinguish Hipporag1 from Hipporag2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7dc27422dd8b4cb8a1384848ddbfa750 | https://github.com/OSU-NLP-Group/HippoRAG/issues/167 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Inquiry on Sample Selection for HippoRAG Experiments\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Inquiry on Sample Selection for HippoRAG Experiments\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6a0069bfedfc4cf28e0cc18e51171a42 | https://github.com/OSU-NLP-Group/HippoRAG/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Quadratic runtime during indexing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Quadratic runtime during indexing\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2681acee71064f72b24098fba0e05227 | https://github.com/OSU-NLP-Group/HippoRAG/issues/170 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b65aca3d12234444b97a67bb7baac278 | https://github.com/OSU-NLP-Group/HippoRAG/issues/178 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：division by zero\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：division by zero\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49e401ba15b74b5d943336fa0a2dceda | https://github.com/OSU-NLP-Group/HippoRAG/issues/93 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | release_recency=unknown\n\n\n",
"markdown_key": "hipporag",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:805115184",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/OSU-NLP-Group/HippoRAG"
},
{
"evidence_id": "art_98797075d8f04ca895317cb9ec83f4a6",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/OSU-NLP-Group/HippoRAG#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "HippoRAG 说明书",
"toc": [
"https://github.com/OSU-NLP-Group/HippoRAG 项目说明书",
"目录",
"项目介绍",
"1 项目概述",
"2 项目背景与动机",
"3 系统架构",
"4 核心功能特性",
"5 关键配置参数",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "d437bfb1805278b81e20c82357ed3f7d90f14901",
"repo_inspection_error": null,
"repo_inspection_files": [
"README.md",
"requirements.txt",
"src/hipporag/HippoRAG.py",
"src/hipporag/StandardRAG.py",
"src/hipporag/embedding_store.py",
"src/hipporag/rerank.py",
"src/hipporag/__init__.py",
"src/hipporag/llm/transformers_llm.py",
"src/hipporag/llm/vllm_offline.py",
"src/hipporag/llm/openai_gpt.py",
"src/hipporag/llm/bedrock_llm.py",
"src/hipporag/llm/__init__.py",
"src/hipporag/llm/transformers_offline.py",
"src/hipporag/llm/base.py",
"src/hipporag/prompts/linking.py",
"src/hipporag/prompts/__init__.py",
"src/hipporag/prompts/prompt_template_manager.py",
"src/hipporag/prompts/filter_default_prompt.py",
"src/hipporag/information_extraction/openie_openai.py",
"src/hipporag/information_extraction/openie_vllm_offline.py",
"src/hipporag/information_extraction/__init__.py",
"src/hipporag/information_extraction/openie_transformers_offline.py",
"src/hipporag/utils/qa_utils.py",
"src/hipporag/utils/eval_utils.py",
"src/hipporag/utils/misc_utils.py",
"src/hipporag/utils/embed_utils.py",
"src/hipporag/utils/logging_utils.py",
"src/hipporag/utils/config_utils.py",
"src/hipporag/utils/typing.py",
"src/hipporag/utils/__init__.py",
"src/hipporag/utils/llm_utils.py",
"src/hipporag/embedding_model/NVEmbedV2.py",
"src/hipporag/embedding_model/GritLM.py",
"src/hipporag/embedding_model/Cohere.py",
"src/hipporag/embedding_model/VLLM.py",
"src/hipporag/embedding_model/OpenAI.py",
"src/hipporag/embedding_model/Transformers.py",
"src/hipporag/embedding_model/Contriever.py",
"src/hipporag/embedding_model/__init__.py",
"src/hipporag/embedding_model/base.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# hipporag - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 hipporag 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install hipporag` 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：研究结论、引用和实验结果不能在安装前相信。\n- **继续会触碰**：研究判断、命令执行、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 现在还不能相信\n\n- **研究结论、引用和实验结果不能在安装前相信。**（unverified）：研究 Skill 可以组织问题和路径，但不能替代真实资料检索、论文核验和实验复现。\n- **是否适合你的具体研究领域不能直接相信。**（unverified）：Skill 覆盖很多研究主题，不代表对你的领域、资料要求和可信度标准足够。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **研究判断**：问题拆解、资料路径、实验路径、结论结构和可信度判断。 原因：研究型 Skill 可能让输出看起来更专业，但不能替代真实证据核验。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `src/hipporag/llm/__init__.py`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先验证它能否正确界定研究问题和证据边界，不要先相信研究输出。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **保留资料和结论核验清单**：如果后续发现引用或实验路径不可靠，可以回到证据边界阶段重新校验。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0004` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：79\n- 重要文件覆盖：30/79\n- 证据索引条目：30\n- 角色 / Skill 条目：5\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 hipporag 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 hipporag 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 hipporag 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 5 个角色 / Skill / 项目文档条目。\n\n- **HippoRAG 2 is a powerful memory framework for LLMs that enhances their ability to recognize and utilize connections in…**（project_doc）：https://colab.research.google.com/drive/1nuelysWsXL8F5xH6q4JYJI8mvtlmeM9O scrollTo=TjHdNe2KC81K 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Readme**（project_doc）：This folder contains all the materials needed for reproducibility of the implementation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`reproduce/README.md`\n- **Readme**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`src/hipporag/evaluation/README.md`\n- **Information for templates folder:**（project_doc）：- Treated as the module under the hipporag project. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`src/hipporag/prompts/templates/README.md`\n- **Contributing to HippoRAG**（project_doc）：Thank you for your interest in contributing to HippoRAG! We are happy to welcome contributions from the community to help us improve our project. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n\n## 证据索引\n\n- 共索引 30 条证据。\n\n- **HippoRAG 2 is a powerful memory framework for LLMs that enhances their ability to recognize and utilize connections in…**（documentation）：https://colab.research.google.com/drive/1nuelysWsXL8F5xH6q4JYJI8mvtlmeM9O scrollTo=TjHdNe2KC81K 证据：`README.md`\n- **Readme**（documentation）：This folder contains all the materials needed for reproducibility of the implementation. 证据：`reproduce/README.md`\n- **Readme**（documentation）：Directory for defining evaluators. 证据：`src/hipporag/evaluation/README.md`\n- **Information for templates folder:**（documentation）：- Treated as the module under the hipporag project. 证据：`src/hipporag/prompts/templates/README.md`\n- **Contributing to HippoRAG**（documentation）：Thank you for your interest in contributing to HippoRAG! We are happy to welcome contributions from the community to help us improve our project. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Copyright c 2025 OSU Natural Language Processing 证据：`LICENSE`\n- **2Wikimultihopqa**（structured_config）：{ \" id\": \"83bf3b5a0bd911eba7f7acde48001122\", \"type\": \"compositional\", \"question\": \"When did Lothair Ii's mother die?\", \"context\": \"Teutberga\", \"Teutberga died 11 November 875 was a queen of Lotharingia by marriage to Lothair II.\", \"She was a daughter of Bosonid Boso the Elder and sister of Hucbert, the lay- abbot of St. Maurice's Abbey.\" , \"Theodred II Bishop of Elmham \", \"Theodred II was a medieval Bishop of Elmham.\", \"The date of Theodred's consecration unknown, but the date of his death was sometime between 995 and 997.\" , \"Lambert, Margrave of Tuscany\", \"Lambert died after 938 was the second son of Adalbert II of Tuscany and Bertha, daughter of Lothair II of Lotharingia.\", \"He succeeded… 证据：`reproduce/dataset/2wikimultihopqa.json`\n- **2Wikimultihopqa Corpus**（structured_config）：{ \"title\": \"Teutberga\", \"text\": \"Teutberga died 11 November 875 was a queen of Lotharingia by marriage to Lothair II. She was a daughter of Bosonid Boso the Elder and sister of Hucbert, the lay- abbot of St. Maurice's Abbey.\" }, { \"title\": \"Theodred II Bishop of Elmham \", \"text\": \"Theodred II was a medieval Bishop of Elmham. The date of Theodred's consecration unknown, but the date of his death was sometime between 995 and 997.\" }, { \"title\": \"Lambert, Margrave of Tuscany\", \"text\": \"Lambert died after 938 was the second son of Adalbert II of Tuscany and Bertha, daughter of Lothair II of Lotharingia. He succeeded his elder brother, Guy, as count and duke of Lucca and margrave of Tuscany on h… 证据：`reproduce/dataset/2wikimultihopqa_corpus.json`\n- **Hotpotqa**（structured_config）：{ \" id\": \"5abe953b5542993f32c2a170\", \"answer\": \"superhero roles as the Marvel Comics\", \"question\": \"what is one of the stars of The Newcomers known for\", \"supporting facts\": \"The Newcomers film \", 0 , \"Chris Evans actor \", 1 , \"context\": \"Vaada Poda Nanbargal\", \"Vaada Poda Nanbargal is a 2011 Indian Tamil-language romantic comedy film directed by Manikai.\", \" P. Arumaichandran has produced this movie under the banner 8 Point Entertainments.\", \" The film stars newcomers Nanda, Sharran Kumar and Yashika in the lead roles.\", \" The lead actor Nanda happens to be one of the strong contender of a popular television series \\\"Yaar Adutha Prabhu Deva\\\" aired on Vijay TV.\" , \"Chris Evans actor \", \"Ch… 证据：`reproduce/dataset/hotpotqa.json`\n- **Hotpotqa Corpus**（structured_config）：{ \"idx\": 0, \"title\": \"Vaada Poda Nanbargal\", \"text\": \"Vaada Poda Nanbargal is a 2011 Indian Tamil-language romantic comedy film directed by Manikai. P. Arumaichandran has produced this movie under the banner 8 Point Entertainments. The film stars newcomers Nanda, Sharran Kumar and Yashika in the lead roles. The lead actor Nanda happens to be one of the strong contender of a popular television series \\\"Yaar Adutha Prabhu Deva\\\" aired on Vijay TV.\" }, { \"idx\": 1, \"title\": \"Chris Evans actor \", \"text\": \"Christopher Robert Evans born June 13, 1981 is an American actor and filmmaker. Evans is known for his superhero roles as the Marvel Comics characters Steve Rogers / Captain America in the Marv… 证据：`reproduce/dataset/hotpotqa_corpus.json`\n- **Musique**（structured_config）：{\"id\": \"2hop 13548 13529\", \"paragraphs\": {\"idx\": 0, \"title\": \"Lionel Messi\", \"paragraph text\": \"After a year at Barcelona's youth academy, La Masia, Messi was finally enrolled in the Royal Spanish Football Federation RFEF in February 2002. Now playing in all competitions, he befriended his teammates, among whom were Cesc F\\u00e0bregas and Gerard Piqu\\u00e9. After completing his growth hormone treatment aged 14, Messi became an integral part of the Baby Dream Team '', Barcelona's greatest - ever youth side. During his first full season 2002 -- 03 , he was top scorer with 36 goals in 30 games for the Cadetes A, who won an unprecedented treble of the league and both the Spanish and Catalan cup… 证据：`reproduce/dataset/musique.json`\n- **Musique Corpus**（structured_config）：{\"title\": \"Lionel Messi\", \"text\": \"After a year at Barcelona's youth academy, La Masia, Messi was finally enrolled in the Royal Spanish Football Federation RFEF in February 2002. Now playing in all competitions, he befriended his teammates, among whom were Cesc F\\u00e0bregas and Gerard Piqu\\u00e9. After completing his growth hormone treatment aged 14, Messi became an integral part of the Baby Dream Team '', Barcelona's greatest - ever youth side. During his first full season 2002 -- 03 , he was top scorer with 36 goals in 30 games for the Cadetes A, who won an unprecedented treble of the league and both the Spanish and Catalan cups. The Copa Catalunya final, a 4 -- 1 victory over Espanyol,… 证据：`reproduce/dataset/musique_corpus.json`\n- **Sample**（structured_config）：{ \"id\": \"sample/question 1.json\", \"question\": \"Which Stanford University professor works on Alzheimer's?\", \"answer\": \"Thomas C. Sudhof\" , \"answerable\": true, \"paragraphs\": { \"title\": \"Thomas C. Sudhof\", \"text\": \"Introduction\\nThomas Christian Sudhof German pronunciation: 'to:mas 'zy:t,ho:f i; born December 22, 1955 , ForMemRS, is a German-American biochemist known for his study of synaptic transmission. Currently, he is a professor in the school of medicine in the department of molecular and cellular physiology, and by courtesy in neurology, and in psychiatry and behavioral sciences at Stanford University.\", \"is supporting\": true, \"idx\": 0 } } 证据：`reproduce/dataset/sample.json`\n- **Sample Corpus**（structured_config）：{ \"title\": \"Thomas C. Sudhof\", \"text\": \"Introduction\\nThomas Christian Sudhof German pronunciation: 'to:mas 'zy:t,ho:f i; born December 22, 1955 , ForMemRS, is a German-American biochemist known for his study of synaptic transmission. Currently, he is a professor in the school of medicine in the department of molecular and cellular physiology, and by courtesy in neurology, and in psychiatry and behavioral sciences at Stanford University.\", \"idx\": 0 }, { \"title\": \"David Eagleman\", \"text\": \"Introduction\\nDavid Eagleman born April 25, 1971 is an American neuroscientist, author, and science communicator. He teaches neuroscience at Stanford University 1 and is CEO and co-founder of Neosensory, a… 证据：`reproduce/dataset/sample_corpus.json`\n- **Filter Llama3.3 70B Instruct**（structured_config）：{ \"prog\": { \"lm\": null, \"traces\": , \"train\": , \"demos\": { \"augmented\": true, \"question\": \"Are Imperial River Florida and Amaradia Dolj both located in the same country?\", \"fact before filter\": \"{\\\"fact\\\": \\\"imperial river\\\", \\\"is located in\\\", \\\"florida\\\" , \\\"imperial river\\\", \\\"is a river in\\\", \\\"united states\\\" , \\\"imperial river\\\", \\\"may refer to\\\", \\\"south america\\\" , \\\"amaradia\\\", \\\"flows through\\\", \\\"ro ia de amaradia\\\" , \\\"imperial river\\\", \\\"may refer to\\\", \\\"united states\\\" }\", \"fact after filter\": \"{\\\"fact\\\": \\\"imperial river\\\",\\\"is located in\\\",\\\"florida\\\" , \\\"imperial river\\\",\\\"is a river in\\\",\\\"united states\\\" , \\\"amaradia\\\",\\\"flows through\\\",\\\"ro ia de amaradia\\\" }\" }, { \"augm… 证据：`src/hipporag/prompts/dspy_prompts/filter_llama3.3-70B-Instruct.json`\n- **Ignore test files**（source_file）：Ignore test files test example.py test example.ipynb ignore log files .log Ignore python compiled caches pycache / .pyc .pyo .pyd Ignore nohup out directory nohup out/ Ignore outputs directory outputs/ Ignore data directory data/ Ignore the bash script to clear files under outputs and logs directories clear outputs and logs.sh Ignore the env file .env 证据：`.gitignore`\n- **Prepare datasets and evaluation**（source_file）：import os from typing import List import json import argparse import logging 证据：`demo.py`\n- **Prepare datasets and evaluation**（source_file）：import os from typing import List import json import argparse import logging 证据：`demo_azure.py`\n- **Prepare datasets and evaluation**（source_file）：def main : Prepare datasets and evaluation docs = \"Oliver Badman is a politician.\", \"George Rankin is a politician.\", \"Thomas Marwick is a politician.\", \"Cinderella attended the royal ball.\", \"The prince used the lost glass slipper to search the kingdom.\", \"When the slipper fit perfectly, Cinderella was reunited with the prince.\", \"Erik Hort's birthplace is Montebello.\", \"Marina is bom in Minsk.\", \"Montebello is a part of Rockland County.\" 证据：`demo_bedrock.py`\n- **Prepare datasets and evaluation**（source_file）：import os from typing import List import json import argparse import logging 证据：`demo_local.py`\n- **Prepare datasets and evaluation**（source_file）：import os from typing import List import json import argparse import logging 证据：`demo_openai.py`\n- **os.environ \"LOG LEVEL\" = \"DEBUG\"**（source_file）：import os from typing import List import json 证据：`main.py`\n- **os.environ \"LOG LEVEL\" = \"DEBUG\"**（source_file）：import os from typing import List import json 证据：`main_azure.py`\n- **os.environ \"LOG LEVEL\" = \"DEBUG\"**（source_file）：import os from typing import List import json 证据：`main_dpr.py`\n- **Requirements**（source_file）：openai==1.91.1 litellm==1.73.1 vllm==0.6.6.post1 gritlm==1.0.2 torch==2.5.1 transformers==4.45.2 networkx==3.4.2 pydantic==2.10.4 python igraph==0.11.8 tenacity==8.5.0 tiktoken==0.7.0 nest asyncio numpy scipy tqdm einops boto3 证据：`requirements.txt`\n- **Setup**（source_file）：with open \"README.md\", \"r\" as f: long description = f.read 证据：`setup.py`\n- **Prepare datasets and evaluation**（source_file）：import os from typing import List import json import argparse import logging 证据：`test_transformers.py`\n- **Prepare datasets and evaluation**（source_file）：import os from typing import List import json import argparse import logging 证据：`tests_azure.py`\n- **Prepare datasets and evaluation**（source_file）：import os from typing import List import json import argparse import logging 证据：`tests_local.py`\n- **Prepare datasets and evaluation**（source_file）：import os from typing import List import json import argparse import logging 证据：`tests_openai.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `reproduce/README.md`, `src/hipporag/evaluation/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `reproduce/README.md`, `src/hipporag/evaluation/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目介绍**：importance `high`\n - source_paths: README.md, src/hipporag/HippoRAG.py\n- **快速入门指南**：importance `high`\n - source_paths: README.md, requirements.txt, demo_openai.py, demo_local.py\n- **系统架构设计**：importance `high`\n - source_paths: src/hipporag/HippoRAG.py, src/hipporag/StandardRAG.py, src/hipporag/embedding_store.py, src/hipporag/utils/config_utils.py\n- **知识图谱构建**：importance `high`\n - source_paths: src/hipporag/HippoRAG.py, src/hipporag/utils/config_utils.py\n- **LLM模型集成**：importance `high`\n - source_paths: src/hipporag/llm/base.py, src/hipporag/llm/openai_gpt.py, src/hipporag/llm/vllm_offline.py, src/hipporag/llm/bedrock_llm.py, src/hipporag/llm/transformers_llm.py\n- **Embedding模型集成**：importance `high`\n - source_paths: src/hipporag/embedding_model/base.py, src/hipporag/embedding_model/NVEmbedV2.py, src/hipporag/embedding_model/GritLM.py, src/hipporag/embedding_model/__init__.py, src/hipporag/embedding_store.py\n- **OpenIE信息抽取**：importance `high`\n - source_paths: src/hipporag/information_extraction/openie_openai.py, src/hipporag/information_extraction/openie_vllm_offline.py, src/hipporag/information_extraction/openie_transformers_offline.py, src/hipporag/prompts/templates/triple_extraction.py, src/hipporag/prompts/templates/ner.py\n- **Prompt模板管理**：importance `medium`\n - source_paths: src/hipporag/prompts/prompt_template_manager.py, src/hipporag/prompts/linking.py, src/hipporag/prompts/filter_default_prompt.py, src/hipporag/prompts/templates/rag_qa_musique.py, src/hipporag/prompts/templates/ircot_hotpotqa.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `d437bfb1805278b81e20c82357ed3f7d90f14901`\n- inspected_files: `README.md`, `requirements.txt`, `src/hipporag/HippoRAG.py`, `src/hipporag/StandardRAG.py`, `src/hipporag/embedding_store.py`, `src/hipporag/rerank.py`, `src/hipporag/__init__.py`, `src/hipporag/llm/transformers_llm.py`, `src/hipporag/llm/vllm_offline.py`, `src/hipporag/llm/openai_gpt.py`, `src/hipporag/llm/bedrock_llm.py`, `src/hipporag/llm/__init__.py`, `src/hipporag/llm/transformers_offline.py`, `src/hipporag/llm/base.py`, `src/hipporag/prompts/linking.py`, `src/hipporag/prompts/__init__.py`, `src/hipporag/prompts/prompt_template_manager.py`, `src/hipporag/prompts/filter_default_prompt.py`, `src/hipporag/information_extraction/openie_openai.py`, `src/hipporag/information_extraction/openie_vllm_offline.py`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：add_fact_edges function adds the same edge twice?\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：add_fact_edges function adds the same edge twice?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_6c7ca8232561460290f1ad50663233af | https://github.com/OSU-NLP-Group/HippoRAG/issues/174 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：pypi hipporag libraries\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：pypi hipporag libraries\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_0da5afa434114138a3c745efba4c9ded | https://github.com/OSU-NLP-Group/HippoRAG/issues/168 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an…\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an extremely long time. Is this normal?\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_90b68b1be49048efba510bfd10623d41 | https://github.com/OSU-NLP-Group/HippoRAG/issues/173 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：OpenAI version incompatibility in latest 2.0.0a4 version\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OpenAI version incompatibility in latest 2.0.0a4 version\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f6679eb5cf884eb9a2d003b39da93c8d | https://github.com/OSU-NLP-Group/HippoRAG/issues/140 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Windows Compatibility Issues with vLLM dependency\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows Compatibility Issues with vLLM dependency\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_57d57b9365f342db9a5e8ed48727e99e | https://github.com/OSU-NLP-Group/HippoRAG/issues/117 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：How to use local embedding_model_\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：How to use local embedding_model_\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_dd0e2350e55240b3ab754359ca93cb11 | https://github.com/OSU-NLP-Group/HippoRAG/issues/127 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_b735fa4a09f942db8f1825092ef8e368 | https://github.com/OSU-NLP-Group/HippoRAG/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：OSU-NLP-Group/HippoRAG\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：chatgpt\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：add_fact_edges function adds the same edge twice?（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：pypi hipporag libraries（high）：可能阻塞安装或首次运行。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an…（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：OpenAI version incompatibility in latest 2.0.0a4 version（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Windows Compatibility Issues with vLLM dependency（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/OSU-NLP-Group/HippoRAG 项目说明书\n\n生成时间：2026-05-16 23:14:33 UTC\n\n## 目录\n\n- [项目介绍](#p1)\n- [快速入门指南](#p2)\n- [系统架构设计](#p3)\n- [知识图谱构建](#p4)\n- [LLM模型集成](#p5)\n- [Embedding模型集成](#p6)\n- [OpenIE信息抽取](#p7)\n- [Prompt模板管理](#p8)\n- [实验复现指南](#p9)\n- [评估与测试](#p10)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[快速入门指南](#p2), [系统架构设计](#p3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [CONTRIBUTING.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/CONTRIBUTING.md)\n- [requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n \n\n# 项目介绍\n\n## 1 项目概述\n\nHippoRAG（海马体RAG）是一个受神经生物学启发的强大图结构RAG框架，能够使大型语言模型（LLM）识别并利用新知识中的关联信息，从而改进检索效果。资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n当前版本为 **HippoRAG 2**，该版本实现了从传统RAG到记忆系统的跨越，引入非参数持续学习（Non-Parametric Continual Learning）能力。资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md#L1)\n\n### 1.1 项目版本信息\n\n| 属性 | 值 |\n|------|-----|\n| 包名称 | hipporag |\n| 当前版本 | 2.0.0-alpha.4 |\n| Python版本要求 | >=3.10 |\n| 许可证 | 开源 |\n| 官方仓库 | https://github.com/OSU-NLP-Group/HippoRAG |\n\n资料来源：[setup.py:1-12](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L1-L12)\n\n## 2 项目背景与动机\n\n### 2.1 传统RAG的局限性\n\n传统检索增强生成（RAG）系统在处理需要跨段落关联推理的问题时存在明显不足。当用户查询需要关联多个分散的知识片段时，传统方法往往难以有效整合相关信息。\n\n### 2.2 HippoRAG的解决方案\n\nHippoRAG从人类海马体的记忆机制中汲取灵感，构建了一个能够模拟人类长期记忆关联特性的图结构知识库。该系统能够：\n\n- 在新知识中识别和利用关联信息\n- 改进跨段落的事实检索能力\n- 支持多跳推理和关联问答\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 3 系统架构\n\n### 3.1 整体架构图\n\n```mermaid\ngraph TD\n subgraph 输入层\n A[文档输入] --> B[OpenIE信息抽取]\n B --> C[知识图谱构建]\n end\n \n subgraph 处理层\n C --> D[嵌入模型编码]\n D --> E[向量索引]\n end\n \n subgraph 检索层\n E --> F[Personalized PageRank检索]\n F --> G[关联节点链接]\n end\n \n subgraph 问答层\n G --> H[LLM问答]\n H --> I[答案输出]\n end\n```\n\n### 3.2 核心模块说明\n\nHippoRAG项目采用模块化设计，核心代码位于`src/hipporag`目录下。资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n| 模块目录 | 功能描述 |\n|---------|---------|\n| `embedding_model/` | 各类嵌入模型的实现 |\n| `evaluation/` | 评估指标实现 |\n| `information_extraction/` | 信息抽取模型实现 |\n| `llm/` | 大语言模型推理类 |\n| `passage/` | 文档处理相关 |\n| `graph/` | 图结构相关 |\n| `retrieval/` | 检索相关 |\n| `config/` | 配置管理 |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 4 核心功能特性\n\n### 4.1 支持的模型类型\n\nHippoRAG支持多种LLM和嵌入模型部署方式：资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n| 模型类型 | 支持方式 | 示例 |\n|---------|---------|------|\n| OpenAI模型 | API调用 | GPT-4o-mini |\n| OpenAI兼容嵌入 | API调用 + 自定义端点 | NVIDIA NV-Embed-v2 |\n| 本地vLLM部署 | 自托管推理 | Llama-3.1-8B-Instruct |\n| Azure OpenAI | Azure云部署 | gpt-4o-mini |\n\n### 4.2 支持的嵌入模型\n\n- **NV-Embed-v2**：NVIDIA开发的嵌入模型\n- **GritLM**：专门用于检索的嵌入模型\n- **Contriever**：基于对比学习的检索模型\n- **OpenAI兼容模型**：支持自定义嵌入端点\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### 4.3 知识图谱构建\n\n系统支持构建多种类型的知识图谱：\n\n```mermaid\ngraph LR\n A[事实节点] --> B[相似段落节点]\n B --> C[单向/双向关联]\n A --> C\n```\n\n**图结构类型**：\n- `facts_and_sim_passage_node_unidirectional`：事实节点与相似段落节点单向关联\n- 支持自定义图结构类型\n\n资料来源：[main.py:1-15](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py#L1-L15)\n\n## 5 关键配置参数\n\n### 5.1 索引构建参数\n\n| 参数名 | 默认值 | 说明 |\n|--------|--------|------|\n| `openie_mode` | - | OpenIE模式（OpenAI/Transformers-offline/vllm） |\n| `information_extraction_model_name` | - | 信息抽取模型名称 |\n| `synonymy_edge_topk` | 2047 | 构建同义词边时的KNN检索参数 |\n| `synonymy_edge_sim_threshold` | 0.8 | 同义词边相似度阈值 |\n| `is_directed_graph` | False | 是否为有向图 |\n\n资料来源：[src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n### 5.2 检索参数\n\n| 参数名 | 默认值 | 说明 |\n|--------|--------|------|\n| `linking_top_k` | 5 | 每次检索步骤链接的节点数 |\n| `retrieval_top_k` | 200 | 每次步骤检索的文档数 |\n| `damping` | 0.5 | PPR算法的阻尼因子 |\n\n资料来源：[src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n### 5.3 问答参数\n\n| 参数名 | 默认值 | 说明 |\n|--------|--------|------|\n| `max_qa_steps` | 1 | 单个问题的最大推理步骤数 |\n| `qa_top_k` | 5 | 输入给QA模型的顶部K个文档 |\n\n资料来源：[src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n## 6 依赖环境\n\n### 6.1 核心依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| torch | 2.5.1 | 深度学习框架 |\n| transformers | 4.45.2 | 模型加载与推理 |\n| vllm | 0.6.6.post1 | 高效LLM推理 |\n| openai | 1.91.1 | OpenAI API调用 |\n| litellm | 1.73.1 | 多模型统一接口 |\n| gritlm | 1.0.2 | 检索嵌入模型 |\n\n资料来源：[setup.py:17-29](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L17-L29)\n\n### 6.2 辅助依赖\n\n| 依赖包 | 版本 | 用途 |\n|--------|------|------|\n| networkx | 3.4.2 | 图结构处理 |\n| python_igraph | 0.11.8 | 图算法实现 |\n| tiktoken | 0.7.0 | 分词器 |\n| pydantic | 2.10.4 | 数据验证 |\n| tenacity | 8.5.0 | 重试机制 |\n| einops | - | 张量操作 |\n| tqdm | - | 进度条 |\n\n资料来源：[requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n\n## 7 数据格式规范\n\n### 7.1 检索语料库格式\n\n```json\n[\n {\n \"title\": \"FIRST PASSAGE TITLE\",\n \"text\": \"FIRST PASSAGE TEXT\",\n \"idx\": 0\n },\n {\n \"title\": \"SECOND PASSAGE TITLE\",\n \"text\": \"SECOND PASSAGE TEXT\",\n \"idx\": 1\n }\n]\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### 7.2 查询数据格式（可选）\n\n```json\n[\n {\n \"id\": \"sample/question_1.json\",\n \"question\": \"QUESTION\",\n \"answer\": [\"ANSWER\"],\n \"answerable\": true,\n \"paragraphs\": [\n {\n \"title\": \"{SUPPORTING PASSAGE TITLE}\",\n \"text\": \"{SUPPORTING PASSAGE TEXT}\",\n \"is_supporting\": true,\n \"idx\": 0\n }\n ]\n }\n]\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 8 使用方式\n\n### 8.1 快速开始流程\n\n```mermaid\ngraph TD\n A[初始化HippoRAG实例] --> B[准备文档数据]\n B --> C[执行索引构建]\n C --> D[执行问答查询]\n D --> E[获取评估结果]\n```\n\n### 8.2 OpenAI模型使用示例\n\n```python\nfrom hipporag import HippoRAG\n\n# 准备数据\ndocs = [\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Erik Hort's birthplace is Montebello.\"\n]\n\n# 初始化实例\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# 索引构建\nhipporag.index(docs)\n\n# 问答查询\nqueries = [\"What is George Rankin's occupation?\"]\nresults = hipporag.rag_qa(queries=queries)\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### 8.3 本地vLLM部署\n\n1. 启动vLLM服务器：\n```sh\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n2. 使用HippoRAG：\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='meta-llama/Llama-3.1-8B-Instruct',\n llm_base_url='http://localhost:6578/v1'\n)\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 9 相关论文\n\n### 9.1 HippoRAG 2（ICML '25）\n\n> From RAG to Memory: Non-Parametric Continual Learning for Large Language Models\n\n- **作者**：Bernal Jiménez Gutiérrez, Yiheng Shu, Weijian Qi, Sizhe Zhou, Yu Su\n- **arXiv**：2502.14802\n\n### 9.2 HippoRAG（NeurIPS '24）\n\n> HippoRAG: Neurobiologically Inspired Long-Term Memory for Large Language Models\n\n- **作者**：Bernal Jiménez Gutiérrez, Yiheng Shu, Yu Gu, Michihiro Yasunaga, Yu Su\n- **OpenReview**：hkujvAPVsg\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 10 项目贡献\n\n### 10.1 贡献流程\n\n1. Fork仓库并克隆到本地\n2. 创建新分支：`git checkout -b my-contribution`\n3. 进行修改并运行测试脚本\n4. 提交更改：`git commit -m \"Add my contribution\"`\n5. 推送分支：`git push origin my-contribution`\n6. 提交Pull Request\n\n### 10.2 测试要求\n\n| 测试类型 | 测试命令 | 适用场景 |\n|---------|---------|---------|\n| OpenAI测试 | `python tests_openai.py` | 使用OpenAI LLM和嵌入模型 |\n| 本地测试 | `python tests_local.py` | 使用vLLM本地部署 |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 11 环境变量配置\n\n| 变量名 | 说明 | 示例 |\n|--------|------|------|\n| `CUDA_VISIBLE_DEVICES` | 可用GPU设备编号 | 0,1,2,3 |\n| `HF_HOME` | HuggingFace缓存目录路径 | /path/to/huggingface |\n| `OPENAI_API_KEY` | OpenAI API密钥 | sk-xxxx |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 12 TODOs与未来规划\n\n- [x] 添加更多嵌入模型支持\n- [x] 添加嵌入端点支持\n- [ ] 添加向量数据库集成支持\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 13 致谢\n\n本项目由俄亥俄州立大学（The Ohio State University）NLP研究组开发维护。\n\n**主要联系人**：\n- Bernal Jiménez Gutiérrez（jimenezgutierrez.1@osu.edu）\n- Yiheng Shu（shu.251@osu.edu）\n- Yu Su（su.809@osu.edu）\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[项目介绍](#p1), [实验复现指南](#p9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [demo_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_openai.py)\n- [demo_local.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_local.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n \n\n# 快速入门指南\n\nHippoRAG 是一个基于图的 RAG（检索增强生成）框架，能够使大型语言模型识别并利用新知识中的关联信息来改进检索效果。本文档将帮助用户在最短时间内完成环境配置和基本功能验证。\n\n## 环境要求\n\n### 系统依赖\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | ≥ 3.10 | 项目必需的 Python 版本 |\n| CUDA | 兼容 | 用于 GPU 加速推理 |\n| conda | 任意稳定版本 | 建议使用 conda 管理虚拟环境 |\n\n资料来源：[setup.py:8]()\n\n### 核心依赖包\n\n项目安装后会自动引入以下核心依赖：\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| torch | 2.5.1 | 深度学习框架 |\n| transformers | 4.45.2 | 模型推理 |\n| vllm | 0.6.6.post1 | 本地 LLM 部署 |\n| openai | 1.91.1 | OpenAI API 调用 |\n| networkx | 3.4.2 | 图数据结构 |\n| pydantic | 2.10.4 | 配置管理 |\n\n资料来源：[setup.py:14-27]()\n\n## 安装步骤\n\n### 方法一：使用 pip 直接安装（推荐）\n\n```sh\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install hipporag\n```\n\n资料来源：[README.md:67-70]()\n\n### 方法二：从源码安装\n\n```sh\ngit clone https://github.com/OSU-NLP-Group/HippoRAG.git\ncd HippoRAG\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install -e .\n```\n\n## 环境变量配置\n\n在运行项目之前，需要配置以下环境变量：\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\nexport OPENAI_API_KEY= # 仅在使用 OpenAI 模型时需要\n```\n\n| 环境变量 | 必填 | 说明 |\n|----------|------|------|\n| CUDA_VISIBLE_DEVICES | 是 | 指定使用的 GPU 编号 |\n| HF_HOME | 是 | Hugging Face 模型缓存目录 |\n| OPENAI_API_KEY | 否 | OpenAI API 密钥（使用 OpenAI 模型时必填） |\n\n资料来源：[README.md:72-76]()\n\n## 快速使用流程\n\nHippoRAG 的核心使用流程分为三个阶段：初始化、索引构建、检索与问答。\n\n```mermaid\ngraph TD\n A[初始化 HippoRAG 实例] --> B[调用 index 方法构建索引]\n B --> C[调用 rag_qa 方法进行检索问答]\n C --> D[获取检索结果和生成答案]\n```\n\n资料来源：[README.md:78-97]()\n\n### 使用 OpenAI 模型\n\n以下示例展示如何使用 OpenAI 模型进行索引构建和问答检索：\n\n```python\nfrom hipporag import HippoRAG\n\n# 准备文档数据\ndocs = [\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Cinderella attended the royal ball.\",\n \"The prince used the lost glass slipper to search the kingdom.\",\n \"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"\n]\n\n# 定义保存目录\nsave_dir = 'outputs'\n\n# 设置模型配置\nllm_model_name = 'gpt-4o-mini'\nembedding_model_name = 'nvidia/NV-Embed-v2'\n\n# 初始化 HippoRAG 实例\nhipporag = HippoRAG(save_dir=save_dir, \n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name)\n\n# 构建索引\nhipporag.index(docs=docs)\n\n# 准备查询和评估数据\nqueries = [\n \"What is George Rankin's occupation?\",\n \"How did Cinderella reach her happy ending?\",\n \"What county is Erik Hort's birthplace a part of?\"\n]\n\nanswers = [\n [\"Politician\"],\n [\"By going to the ball.\"],\n [\"Rockland County\"]\n]\n\ngold_docs = [\n [\"George Rankin is a politician.\"],\n [\"Cinderella attended the royal ball.\",\n \"The prince used the lost glass slipper to search the kingdom.\",\n \"When the slipper fit perfectly, Cinderella was reunited with the prince.\"],\n [\"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"]\n]\n\n# 执行检索和问答\nrag_results = hipporag.rag_qa(queries=queries, \n gold_docs=gold_docs,\n gold_answers=answers)\n```\n\n资料来源：[README.md:78-97]()\n\n### 使用本地 vLLM 部署\n\n#### 第一步：启动 vLLM 服务器\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nconda activate hipporag\n\n# 根据 GPU 内存调整参数\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n资料来源：[README.md:106-113]()\n\n#### 第二步：运行主程序\n\n```sh\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=\n\npython main.py --dataset sample --llm_base_url http://localhost:6578/v1 \\\n --llm_name meta-llama/Llama-3.1-8B-Instruct \\\n --embedding_name nvidia/NV-Embed-v2\n```\n\n资料来源：[README.md:115-120]()\n\n### 使用 OpenAI 兼容端点\n\n如果使用第三方 OpenAI 兼容的 LLM 和 Embedding 服务：\n\n```python\nhipporag = HippoRAG(save_dir=save_dir, \n llm_model_name='Your LLM Model name',\n llm_base_url='Your LLM Model url',\n embedding_model_name='Your Embedding model name', \n embedding_base_url='Your Embedding model url')\n```\n\n资料来源：[README.md:100-103]()\n\n### 使用 Azure OpenAI\n\n```python\nhipporag = HippoRAG(save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name,\n azure_endpoint=\"https://[ENDPOINT NAME].openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2025-01-01-preview\",\n azure_embedding_endpoint=\"https://[ENDPOINT NAME].openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2023-05-15\")\n```\n\n资料来源：[demo_openai.py:1-5]()\n\n## 核心配置参数\n\n`BaseConfig` 类包含所有可配置参数，以下是常用参数说明：\n\n| 参数名 | 默认值 | 类型 | 说明 |\n|--------|--------|------|------|\n| llm_model_name | - | str | LLM 模型名称 |\n| embedding_model_name | nvidia/NV-Embed-v2 | str | Embedding 模型名称 |\n| llm_base_url | - | str | LLM API 端点 URL |\n| embedding_base_url | - | str | Embedding API 端点 URL |\n| linking_top_k | 5 | int | 每次检索步骤链接的节点数 |\n| retrieval_top_k | 200 | int | 每次检索的文档数量 |\n| qa_top_k | 5 | int | 输入给 QA 模型的 Top-K 文档数 |\n| max_qa_steps | 1 | int | 最大问答迭代步数 |\n| openie_mode | online | str | OpenIE 模型模式（online/offline） |\n| embedding_batch_size | 16 | int | Embedding 模型批处理大小 |\n\n资料来源：[src/hipporag/utils/config_utils.py:1-50]()\n\n## 数据集格式\n\n### 检索语料库格式\n\n```json\n[\n {\n \"title\": \"FIRST PASSAGE TITLE\",\n \"text\": \"FIRST PASSAGE TEXT\",\n \"idx\": 0\n },\n {\n \"title\": \"SECOND PASSAGE TITLE\",\n \"text\": \"SECOND PASSAGE TEXT\",\n \"idx\": 1\n }\n]\n```\n\n资料来源：[README.md:141-151]()\n\n### 查询文件格式（可选）\n\n```json\n[\n {\n \"id\": \"sample/question_1.json\",\n \"question\": \"QUESTION\",\n \"answer\": [\"ANSWER\"],\n \"answerable\": true,\n \"paragraphs\": [\n {\n \"title\": \"{SUPPORTING PASSAGE TITLE}\",\n \"text\": \"{SUPPORTING PASSAGE TEXT}\",\n \"is_supporting\": true,\n \"idx\": 0\n }\n ]\n }\n]\n```\n\n资料来源：[README.md:153-170]()\n\n## 验证安装\n\n### 使用 OpenAI 模型验证\n\n```sh\nexport OPENAI_API_KEY= \nconda activate hipporag\npython tests_openai.py\n```\n\n资料来源：[README.md:124-128]()\n\n### 使用本地模型验证\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nconda activate hipporag\n\n# 启动 vLLM 服务器\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n\n# 运行测试\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:130-144]()\n\n## 常见问题排查\n\n### GPU 内存不足\n\n如果遇到 OOM（内存溢出）错误，可以调整以下参数：\n\n- 降低 `gpu-memory-utilization` 值（建议从 0.95 逐步下调）\n- 减小 `max_model_len` 参数\n- 减少 `CUDA_VISIBLE_DEVICES` 中指定的 GPU 数量\n\n资料来源：[README.md:109-112]()\n\n### 索引构建缓慢\n\n建议增加 `embedding_batch_size` 参数的值，默认值为 16，可根据 GPU 显存调整为 32 或更高。\n\n资料来源：[main.py:12]()\n\n## 后续步骤\n\n完成快速入门后，建议进一步阅读以下内容：\n\n- **高级配置**：调整 `BaseConfig` 中的参数以优化检索效果\n- **增量更新**：使用 `index` 方法对新增文档进行增量索引\n- **实验复现**：参考 `main.py` 的实现方式运行论文中的实验\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目介绍](#p1), [知识图谱构建](#p4), [LLM模型集成](#p5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)\n- [src/hipporag/StandardRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/StandardRAG.py)\n- [src/hipporag/embedding_store.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_store.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n \n\n# 系统架构设计\n\n## 概述\n\nHippoRAG是一个受神经生物学启发的图基RAG（检索增强生成）框架，旨在使大型语言模型能够识别并利用新知识中的关联信息以改进检索效果。该系统通过模拟海马体的记忆索引机制，实现高效的持久化知识管理和关联推理能力。\n\nHippoRAG的核心架构围绕三个主要阶段设计：**索引（Indexing）**、**检索（Retrieval）** 和 **问答（QA）**。系统支持多种LLM后端（OpenAI、vLLM、Azure OpenAI）和嵌入模型（NV-Embed-v2、GritLM、Contriever等），提供了灵活的部署选项。\n\n## 核心模块架构\n\n### 模块层次结构\n\nHippoRAG项目采用清晰的模块化设计，各组件职责明确：\n\n| 模块路径 | 功能描述 | 核心类/文件 |\n|---------|---------|------------|\n| `hipporag/embedding_model/` | 嵌入模型实现 | `BaseEmbeddingModel`, `NVEmbedV2` |\n| `hipporag/evaluation/` | 评估指标 | `BaseMetric`, `qa_eval.py`, `retrieval_eval.py` |\n| `hipporag/information_extraction/` | 信息抽取 | `openie_openai_gpt.py`, `openie_vllm_offline.py` |\n| `hipporag/llm/` | 大语言模型推理 | 各类LLM调用封装 |\n| `hipporag/utils/` | 工具函数 | `config_utils.py` |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### 主要类层次\n\nHippoRAG中存在两种主要的RAG实现类：\n\n```mermaid\nclassDiagram\n class BaseRAG {\n <>\n +index(docs)\n +rag_qa(queries, gold_docs, gold_answers)\n +delete(docs)\n }\n class HippoRAG {\n +index(docs)\n +rag_qa(queries, gold_docs, gold_answers)\n +delete(docs)\n }\n class StandardRAG {\n +index(docs)\n +rag_qa(queries, gold_docs, gold_answers)\n }\n \n BaseRAG <|-- HippoRAG\n BaseRAG <|-- StandardRAG\n```\n\n**HippoRAG** 类提供完整的图基索引和Personalized PageRank检索能力，而 **StandardRAG** 类实现传统的密集检索方法。\n\n## 配置系统\n\n### 配置架构\n\nHippoRAG使用Pydantic的`BaseConfig`类作为配置基础，提供类型安全的配置管理：\n\n```python\nclass BaseConfig(BaseModel):\n # OpenIE配置\n openie_mode: Literal['OpenAI', 'vLLM-offline', 'Transformers-offline']\n information_extraction_model_name: str\n \n # Embedding模型配置\n embedding_model_name: str\n embedding_batch_size: int = 16\n embedding_return_as_normalized: bool = True\n embedding_max_seq_len: int = 2048\n embedding_model_dtype: Literal[\"float16\", \"float32\", \"bfloat16\", \"auto\"]\n \n # 图构建配置\n synonymy_edge_topk: int = 2047\n synonymy_edge_query_batch_size: int = 1000\n synonymy_edge_key_batch_size: int = 10000\n synonymy_edge_sim_threshold: float = 0.8\n \n # 检索配置\n linking_top_k: int = 5\n retrieval_top_k: int = 200\n damping: float = 0.5\n \n # QA配置\n max_qa_steps: int = 1\n qa_top_k: int = 5\n \n # 保存路径\n save_dir: str = \"outputs\"\n```\n\n资料来源：[src/hipporag/utils/config_utils.py:1-100](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n### 关键配置参数\n\n#### OpenIE模式配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `openie_mode` | str | - | 信息抽取模式：OpenAI/vLLM-offline/Transformers-offline |\n| `information_extraction_model_name` | str | - | 信息抽取使用的模型名称 |\n\n#### 嵌入模型配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `embedding_model_name` | str | - | 嵌入模型名称（nvidia/NV-Embed-v2等） |\n| `embedding_batch_size` | int | 16 | 嵌入调用批次大小 |\n| `embedding_return_as_normalized` | bool | True | 是否返回归一化嵌入 |\n| `embedding_max_seq_len` | int | 2048 | 嵌入模型最大序列长度 |\n| `embedding_model_dtype` | str | \"auto\" | 模型数据类型 |\n\n#### 图构建配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `synonymy_edge_topk` | int | 2047 | 构建同义边时的KNN检索K值 |\n| `synonymy_edge_query_batch_size` | int | 1000 | 同义边查询批大小 |\n| `synonymy_edge_key_batch_size` | int | 10000 | 同义边键批大小 |\n| `synonymy_edge_sim_threshold` | float | 0.8 | 同义边相似度阈值 |\n| `is_directed_graph` | bool | False | 图是否是有向图 |\n\n#### 检索与QA配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `linking_top_k` | int | 5 | 每次检索步骤关联的节点数 |\n| `retrieval_top_k` | int | 200 | 初始检索文档数 |\n| `damping` | float | 0.5 | PageRank阻尼因子 |\n| `max_qa_steps` | int | 1 | QA最大迭代步数 |\n| `qa_top_k` | int | 5 | 输入QA模型的顶部文档数 |\n\n## 索引流程架构\n\n### 索引阶段工作流\n\nHippoRAG的索引阶段将文档转化为知识图谱，实现与海马体记忆索引类似的持久化存储：\n\n```mermaid\ngraph TD\n A[输入文档列表] --> B[文本分割]\n B --> C[OpenIE信息抽取]\n C --> D[生成事实三元组]\n D --> E[实体节点提取]\n E --> F[构建段落节点]\n F --> G[生成实体-段落边]\n G --> H[KNN同义边构建]\n H --> I[段落相似边构建]\n I --> J[持久化图结构存储]\n \n C --> K[文档嵌入生成]\n K --> L[向量存储]\n```\n\n### 核心索引组件\n\nHippoRAG使用`embedding_store`模块管理向量存储，该模块负责：\n\n1. **文档嵌入**：使用配置的嵌入模型对文档进行向量化\n2. **向量索引**：构建高效的向量检索索引\n3. **相似度计算**：支持归一化和非归一化嵌入的相似度计算\n\n索引过程的关键调用示例：\n\n```python\n# main.py中的索引调用\nhipporag = HippoRAG(global_config=config)\nhipporag.index(docs)\n```\n\n资料来源：[main.py:1-30](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n## 检索流程架构\n\n### Personalized PageRank检索\n\nHippoRAG采用Personalized PageRank（PPR）算法进行关联检索，区别于传统的向量相似度检索：\n\n```mermaid\ngraph LR\n A[查询] --> B[向量相似度检索]\n B --> C[获取初始候选节点]\n C --> D[构建查询图]\n D --> E[PPR迭代计算]\n E --> F[节点重要性排序]\n F --> G[返回关联段落]\n```\n\n### 检索配置参数\n\n| 参数 | 说明 | 影响 |\n|------|------|------|\n| `retrieval_top_k` | 初始向量检索返回的文档数 | 候选集大小，影响PPR计算范围 |\n| `linking_top_k` | 每步关联的节点数 | 检索的深度和广度 |\n| `damping` | PPR阻尼因子 | 随机跳转概率，影响收敛速度 |\n| `synonymy_edge_sim_threshold` | 同义边相似度阈值 | 控制哪些实体被视为同义 |\n\n检索过程中，系统通过同义边（synonymy edges）建立实体间的语义关联，实现跨段落的事实关联发现。\n\n## 问答流程架构\n\n### 多步推理问答\n\nHippoRAG支持迭代式问答，通过多步检索-推理交替提升答案质量：\n\n```mermaid\ngraph TD\n A[问题输入] --> B[Step 1: 检索相关段落]\n B --> C[Step 1: LLM推理]\n C --> D{达到最大步数?}\n D -->|否| E[基于推理结果重检索]\n E --> B\n D -->|是| F[生成最终答案]\n B --> G[Top-K段落收集]\n G --> F\n```\n\n### QA配置参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `max_qa_steps` | 1 | 最大问答迭代步数 |\n| `qa_top_k` | 5 | 输入LLM的顶部文档数 |\n\n调用示例：\n\n```python\nrag_results = hipporag.rag_qa(\n queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers\n)\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 部署架构\n\n### 多后端支持\n\nHippoRAG支持多种LLM和嵌入模型部署方式：\n\n#### OpenAI模型部署\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n```\n\n#### Azure OpenAI部署\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\n azure_endpoint=\"https://[ENDPOINT].openai.azure.com/...\",\n azure_embedding_endpoint=\"https://[ENDPOINT].openai.azure.com/...\"\n)\n```\n\n#### vLLM本地部署\n\n```bash\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='meta-llama/Llama-3.1-8B-Instruct',\n llm_model_port=6578,\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n```\n\n### 依赖架构\n\nHippoRAG的核心依赖层次：\n\n| 依赖层级 | 库 | 版本 | 用途 |\n|---------|-----|------|------|\n| 深度学习框架 | torch | 2.5.1 | Tensor计算 |\n| 推理框架 | vLLM | 0.6.6.post1 | 本地LLM推理 |\n| 嵌入模型 | transformers | 4.45.2 | 模型加载 |\n| 图计算 | networkx | 3.4.2 | 图结构操作 |\n| 图算法 | python_igraph | 0.11.8 | 图算法实现 |\n| API调用 | openai | 1.91.1 | OpenAI API |\n| 向量嵌入 | gritlm | 1.0.2 | GritLM嵌入模型 |\n| 数据验证 | pydantic | 2.10.4 | 配置管理 |\n| 重试机制 | tenacity | 8.5.0 | 容错处理 |\n| 分词 | tiktoken | 0.7.0 | Token计数 |\n\n资料来源：[setup.py:1-30](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n\n## 数据流架构\n\n### 完整RAG流程\n\n```mermaid\nflowchart TB\n subgraph 索引阶段[\"索引阶段\"]\n I1[加载配置] --> I2[文档预处理]\n I2 --> I3[OpenIE抽取]\n I3 --> I4[构建事实图谱]\n I4 --> I5[向量索引]\n I5 --> I6[持久化存储]\n end\n \n subgraph 检索阶段[\"检索阶段\"]\n Q1[用户查询] --> Q2[查询向量化]\n Q2 --> Q3[向量相似度检索]\n Q3 --> Q4[初始候选集]\n Q4 --> Q5[PPR图遍历]\n Q5 --> Q6[关联段落排序]\n end\n \n subgraph QA阶段[\"问答阶段\"]\n QA1[相关段落] --> QA2[Prompt构建]\n QA2 --> QA3[LLM推理]\n QA3 --> QA4{迭代判断}\n QA4 -->|继续| QA5[重检索]\n QA5 --> QA2\n QA4 -->|完成| QA6[答案生成]\n end\n \n I6 --> Q1\n Q6 --> QA1\n```\n\n## 项目结构\n\n```\nsrc/hipporag/\n├── HippoRAG.py # 核心HippoRAG类实现\n├── StandardRAG.py # 标准RAG实现\n├── embedding_store.py # 向量存储管理\n├── __init__.py\n├── embedding_model/ # 嵌入模型模块\n│ ├── __init__.py\n│ ├── base.py # 基类定义\n│ └── NVEmbedV2.py # NV-Embed-v2实现\n├── evaluation/ # 评估模块\n│ ├── __init__.py\n│ ├── base.py # 评估基类\n│ ├── qa_eval.py # QA评估\n│ └── retrieval_eval.py # 检索评估\n├── information_extraction/ # 信息抽取模块\n│ ├── __init__.py\n│ ├── openie_openai_gpt.py\n│ └── openie_vllm_offline.py\n├── llm/ # LLM推理模块\n└── utils/\n ├── __init__.py\n └── config_utils.py # 配置工具\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 总结\n\nHippoRAG的系统架构设计体现了以下核心原则：\n\n1. **模块化设计**：各功能模块（嵌入模型、信息抽取、图构建、检索、QA）职责清晰，便于扩展和维护\n\n2. **配置驱动**：通过`BaseConfig`类实现类型安全的配置管理，支持多种部署场景\n\n3. **海马体启发的持久化索引**：通过OpenIE抽取事实知识并构建异构图，实现长期记忆的持久化存储\n\n4. **PPR关联检索**：采用Personalized PageRank算法挖掘实体间的语义关联，克服传统向量检索的局限性\n\n5. **多后端兼容**：统一接口支持OpenAI、vLLM、Azure等多种部署方式，提高系统灵活性\n\n---\n\n\n\n## 知识图谱构建\n\n### 相关页面\n\n相关主题：[系统架构设计](#p3), [OpenIE信息抽取](#p7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py) (README.md中的代码结构引用)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py) (使用示例)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py) (依赖声明)\n \n\n# 知识图谱构建\n\nHippoRAG的知识图谱构建是整个框架的核心组件，负责将原始文档语料转化为结构化的图知识表示。该模块整合了开放信息抽取（OpenIE）、嵌入向量计算和图连接构建等技术，实现了类似人类海马体的知识组织和关联机制。\n\n## 核心配置参数\n\n知识图谱构建通过`BaseConfig`类进行配置管理，主要涉及以下关键参数：\n\n| 参数名称 | 默认值 | 说明 |\n|---------|--------|------|\n| `graph_type` | `facts_and_sim_passage_node_unidirectional` | 图类型，定义节点和边的组织方式 |\n| `openie_mode` | `openai-gpt` | 开放信息抽取模式 |\n| `information_extraction_model_name` | `gpt-4o-mini` | 信息抽取使用的模型名称 |\n| `synonymy_edge_topk` | `2047` | 构建同义词边时KNN检索的K值 |\n| `synonymy_edge_sim_threshold` | `0.8` | 同义词边的相似度阈值 |\n| `is_directed_graph` | `False` | 图是否为有向图 |\n\n资料来源：[config_utils.py:参数定义](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n## 图谱构建流程\n\n知识图谱的构建遵循以下标准化流程：\n\n```mermaid\ngraph TD\n A[原始文档输入] --> B[分块与预处理]\n B --> C[开放信息抽取 OpenIE]\n C --> D[事实三元组提取]\n C --> E[段落节点创建]\n D --> F[事实节点与段落节点连接]\n E --> F\n F --> G[嵌入向量计算]\n G --> H[同义词边构建 KNN]\n H --> I[个性化PageRank检索准备]\n I --> J[知识图谱输出]\n```\n\n1. **文档输入与预处理**：接收原始文本语料，按照配置进行必要的分块处理\n2. **开放信息抽取**：使用OpenIE模型从文本中提取事实三元组（主语-谓词-宾语）\n3. **节点创建**：生成两类核心节点——事实节点（Fact Node）和段落节点（Passage Node）\n4. **边构建**：基于语义相似度和实体关联建立节点间的连接关系\n5. **图谱索引**：完成图结构的持久化存储，为后续检索做好准备\n\n资料来源：[README.md:代码结构](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 图类型配置\n\nHippoRAG支持多种图谱拓扑结构，通过`graph_type`参数进行选择：\n\n| 图类型 | 描述 | 适用场景 |\n|-------|------|---------|\n| `facts_and_sim_passage_node_unidirectional` | 事实节点与段落节点单向连接，含同义词边 | 默认配置，适合大多数问答场景 |\n| `facts_and_sim_passage_node_bidirectional` | 事实节点与段落节点双向连接 | 需要更密集的信息流动 |\n| `facts_passage_node` | 仅含事实边和段落节点 | 轻量级图谱，减少计算开销 |\n\n同义词边的构建采用KNN（K近邻）算法，在嵌入向量空间中寻找语义相似的节点对：\n\n```python\nsynonymy_edge_topk: int = 2047 # KNN检索的K值\nsynonymy_edge_query_batch_size: int = 1000 # 查询嵌入批次大小\nsynonymy_edge_key_batch_size: int = 10000 # 键嵌入批次大小\nsynonymy_edge_sim_threshold: float = 0.8 # 相似度阈值\n```\n\n资料来源：[config_utils.py:图构建参数](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n## 开放信息抽取模式\n\nHippoRAG支持两种OpenIE实现方式：\n\n| 模式 | 说明 | 依赖 |\n|------|------|------|\n| `openai-gpt` | 使用OpenAI GPT模型进行信息抽取 | `OPENAI_API_KEY`环境变量 |\n| `vllm-offline` | 使用本地vLLM部署的模型 | vLLM服务配置 |\n| `Transformers-offline` | 使用Transformers库本地加载模型 | GPU显存充足 |\n\n信息抽取模块位于`src/hipporag/information_extraction/`目录，包含以下实现：\n\n- `openie_openai_gpt.py`：OpenAI GPT模型的OpenIE实现\n- `openie_vllm_offline.py`：vLLM离线部署模型的OpenIE实现\n\n资料来源：[README.md:信息抽取模块](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 索引构建接口\n\nHippoRAG通过`HippoRAG`类提供统一的索引构建接口：\n\n```python\nfrom hipporag import HippoRAG\n\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# 文档索引构建\nhipporag.index(docs=[\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Erik Hort's birthplace is Montebello.\"\n])\n```\n\n配置参数可通过`global_config`或构造函数直接传入：\n\n```python\nconfig = BaseConfig(\n graph_type=\"facts_and_sim_passage_node_unidirectional\",\n synonymy_edge_topk=2047,\n synonymy_edge_sim_threshold=0.8,\n embedding_batch_size=8,\n openie_mode='openai-gpt',\n information_extraction_model_name='gpt-4o-mini'\n)\n\nhipporag = HippoRAG(global_config=config, ...)\n```\n\n资料来源：[main.py:索引配置](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n## 嵌入模型配置\n\n图谱构建过程中的向量计算支持多种嵌入模型：\n\n| 模型类型 | 模型名称示例 | 配置方式 |\n|---------|-------------|---------|\n| NVIDIA | `nvidia/NV-Embed-v2` | 直接指定模型名 |\n| GritLM | `GritLM` | 通过`embedding_model_name`指定 |\n| Contriever | `Contriever` | 通过`embedding_model_name`指定 |\n| OpenAI兼容 | 自定义模型 | `embedding_base_url`指定端点 |\n| Azure OpenAI | `text-embedding-3-small` | `azure_embedding_endpoint`配置 |\n\n嵌入相关配置参数：\n\n| 参数 | 默认值 | 说明 |\n|-----|--------|------|\n| `embedding_batch_size` | 16 | 嵌入计算的批次大小 |\n| `embedding_return_as_normalized` | True | 是否返回归一化向量 |\n| `embedding_max_seq_len` | 2048 | 最大序列长度 |\n| `embedding_model_dtype` | `auto` | 数据类型（float16/float32/bfloat16/auto） |\n\n资料来源：[config_utils.py:嵌入配置](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n\n## 依赖组件\n\n知识图谱构建依赖以下核心库：\n\n| 依赖库 | 版本 | 用途 |\n|-------|------|------|\n| `networkx` | 3.4.2 | 图数据结构与算法实现 |\n| `python_igraph` | 0.11.8 | 图可视化与分析 |\n| `torch` | 2.5.1 | 深度学习张量计算 |\n| `transformers` | 4.45.2 | 预训练模型加载 |\n| `gritlm` | 1.0.2 | GritLM嵌入模型支持 |\n| `tiktoken` | 0.7.0 | Tokenization |\n| `pydantic` | 2.10.4 | 配置数据验证 |\n\n资料来源：[setup.py:依赖声明](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n\n## 增量更新与删除\n\nHippoRAG支持对已构建的图谱进行增量操作：\n\n```python\n# 添加新文档\nhipporag.index(docs=[\"新文档内容...\"])\n\n# 删除指定文档\nhipporag.delete(docs_to_delete=[\"要删除的文档...\"])\n\n# 验证更新效果\nresult = hipporag.rag_qa(queries=queries, \n gold_docs=gold_docs, \n gold_answers=answers)\n```\n\n增量更新会重新计算相关节点的嵌入向量，并更新图中的连接关系。\n\n资料来源：[tests_openai.py:增量操作](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)\n\n## 环境变量配置\n\n图谱构建前需正确配置以下环境变量：\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0,1,2,3 # GPU设备选择\nexport HF_HOME= # HuggingFace模型缓存目录\nexport OPENAI_API_KEY= # OpenAI API密钥（使用OpenAI模式时）\n```\n\n资料来源：[README.md:环境配置](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n---\n\n\n\n## LLM模型集成\n\n### 相关页面\n\n相关主题：[系统架构设计](#p3), [Embedding模型集成](#p6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/llm/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)\n- [src/hipporag/llm/openai_gpt.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/openai_gpt.py)\n- [src/hipporag/llm/vllm_offline.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/vllm_offline.py)\n- [src/hipporag/llm/bedrock_llm.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/bedrock_llm.py)\n- [src/hipporag/llm/transformers_llm.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/transformers_llm.py)\n \n\n# LLM模型集成\n\n## 概述\n\nHippoRAG的LLM模型集成模块提供了一套统一的接口，用于对接多种大语言模型提供商。该模块位于`src/hipporag/llm/`目录下，通过抽象基类`LLMInterface`定义标准接口，各具体实现类继承该基类以支持不同的模型服务。\n\n主要支持以下模型服务：\n\n| 提供商 | 实现类 | 特点 |\n|--------|--------|------|\n| OpenAI | `OpenAIGPT` | 云端API调用，支持自定义endpoint |\n| vLLM | `VLLMOffline` | 本地离线推理，高吞吐量 |\n| AWS Bedrock | `BedrockLLM` | 云端托管，支持Claude等模型 |\n| HuggingFace Transformers | `TransformersLLM` | 本地transformers库推理 |\n\n资料来源：[base.py:1-20](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)\n\n## 架构设计\n\n### 类层次结构\n\nHippoRAG采用面向对象设计模式，通过抽象基类定义统一接口规范：\n\n```mermaid\ngraph TD\n A[LLMInterface
抽象基类] --> B[OpenAIGPT]\n A --> C[VLLMOffline]\n A --> D[BedrockLLM]\n A --> E[TransformersLLM]\n \n F[调用方] --> A\n```\n\n### 接口规范\n\n`LLMInterface`定义了所有LLM实现必须遵循的核心方法：\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `__call__` | `prompt`, `system_prompt`, `keyword` | `str` | 同步调用接口 |\n| `batch_call` | `prompts`, `system_prompts`, `keywords` | `List[str]` | 批量调用接口 |\n| `_call` | `prompt`, `system_prompt`, `keyword` | `str` | 具体实现方法 |\n| `_batch_call` | `prompts`, `system_prompts`, `keywords` | `List[str]` | 批量实现方法 |\n\n资料来源：[base.py:10-60](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)\n\n## 核心实现\n\n### 基础抽象类\n\n基础类`LLMInterface`位于`base.py`，采用ABC抽象基类模式：\n\n```python\nclass LLMInterface(ABC):\n def __init__(\n self,\n model_name: str,\n api_key: str = None,\n api_base: str = None,\n timeout: int = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\n关键配置参数说明：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model_name` | `str` | 必填 | 模型标识符 |\n| `api_key` | `str` | `None` | API密钥 |\n| `api_base` | `str` | `None` | API服务端点 |\n| `timeout` | `int` | `120` | 超时时间（秒） |\n| `max_tokens` | `int` | `256` | 最大生成token数 |\n| `temperature` | `float` | `0.0` | 采样温度 |\n| `request_timeout` | `int` | `120` | 请求超时 |\n| `top_p` | `float` | `1.0` | 核采样概率 |\n\n资料来源：[base.py:10-25](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/base.py)\n\n### OpenAI GPT集成\n\n`OpenAIGPT`类封装了OpenAI API的调用逻辑：\n\n```python\nclass OpenAIGPT(LiteLLM):\n def __init__(\n self,\n model_name: str = \"gpt-3.5-turbo\",\n api_key: str = None,\n api_base: str = None,\n timeout: float = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\n支持的模型包括：\n- `gpt-4`\n- `gpt-4-turbo`\n- `gpt-4o`\n- `gpt-3.5-turbo`\n- `gpt-3.5-turbo-16k`\n\n资料来源：[openai_gpt.py:15-40](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/openai_gpt.py)\n\n### vLLM离线推理\n\n`VLLMOffline`类支持本地vLLM服务器推理，适用于需要离线或私有化部署的场景：\n\n```python\nclass VLLMOffline(LiteLLM):\n def __init__(\n self,\n model_name: str,\n api_base: str,\n api_key: str = \"EMPTY\",\n timeout: float = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\n特点：\n- 默认使用`api_key = \"EMPTY\"`简化本地部署认证\n- 支持批量请求提升吞吐量\n- 可对接任何兼容OpenAI API格式的vLLM服务端\n\n资料来源：[vllm_offline.py:1-50](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/vllm_offline.py)\n\n### AWS Bedrock集成\n\n`BedrockLLM`类提供对AWS Bedrock平台模型的支持：\n\n```python\nclass BedrockLLM(LiteLLM):\n def __init__(\n self,\n model_name: str,\n aws_access_key: str = None,\n aws_secret_key: str = None,\n aws_region_name: str = \"us-east-1\",\n timeout: float = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\nAWS特定配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `aws_access_key` | `str` | `None` | AWS访问密钥 |\n| `aws_secret_key` | `str` | `None` | AWS秘密密钥 |\n| `aws_region_name` | `str` | `\"us-east-1\"` | AWS区域 |\n\n支持的Bedrock模型：\n- Claude系列（通过Anthropic）\n- Titan系列\n- Llama系列\n\n资料来源：[bedrock_llm.py:1-60](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/bedrock_llm.py)\n\n### HuggingFace Transformers\n\n`TransformersLLM`类支持直接使用HuggingFace transformers库进行本地推理：\n\n```python\nclass TransformersLLM(LiteLLM):\n def __init__(\n self,\n model_name: str,\n model_path: str = None,\n auth_token: str = None,\n device: str = \"cuda\",\n timeout: float = 120,\n max_tokens: int = 256,\n temperature: float = 0.0,\n request_timeout: int = 120,\n top_p: float = 1.0,\n **kwargs\n ):\n```\n\nHuggingFace特定配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model_name` | `str` | 必填 | HuggingFace模型标识 |\n| `model_path` | `str` | `None` | 本地模型路径 |\n| `auth_token` | `str` | `None` | HuggingFace认证令牌 |\n| `device` | `str` | `\"cuda\"` | 运行设备（cuda/cpu） |\n\n资料来源：[transformers_llm.py:1-60](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/transformers_llm.py)\n\n## 使用流程\n\n### 初始化与调用流程\n\n```mermaid\ngraph TD\n A[选择LLM类型] --> B{场景需求}\n B -->|云端API| C[OpenAIGPT / BedrockLLM]\n B -->|本地推理| D{vLLM or Transformers}\n D -->|批量高吞吐| E[VLLMOffline]\n D -->|灵活部署| F[TransformersLLM]\n \n C --> G[配置API密钥和端点]\n E --> H[启动vLLM服务]\n F --> I[下载/加载模型]\n \n G --> J[实例化LLM对象]\n H --> J\n I --> J\n \n J --> K[调用__call__方法]\n K --> L[返回生成结果]\n```\n\n### 代码示例\n\n```python\nfrom hipporag.llm import OpenAIGPT, VLLMOffline, TransformersLLM\n\n# OpenAI API调用\nllm = OpenAIGPT(\n model_name=\"gpt-4\",\n api_key=\"your-api-key\",\n temperature=0.0,\n max_tokens=256\n)\nresponse = llm(\"你的问题\", system_prompt=\"你是一个助手\")\n\n# vLLM离线调用\nllm_offline = VLLMOffline(\n model_name=\"meta-llama/Llama-2-7b-chat-hf\",\n api_base=\"http://localhost:8000/v1\",\n temperature=0.0\n)\nresponse = llm_offline(\"你的问题\")\n```\n\n## 配置选项汇总\n\n| 配置项 | 适用类 | 说明 |\n|--------|--------|------|\n| `model_name` | 所有 | 模型名称或路径 |\n| `api_key` | OpenAI/Bedrock/vLLM | 认证密钥 |\n| `api_base` | OpenAI/vLLM | API服务端点 |\n| `aws_access_key` | Bedrock | AWS访问密钥 |\n| `aws_secret_key` | Bedrock | AWS秘密密钥 |\n| `aws_region_name` | Bedrock | AWS区域 |\n| `auth_token` | Transformers | HuggingFace令牌 |\n| `model_path` | Transformers | 本地模型路径 |\n| `device` | Transformers | 计算设备 |\n| `timeout` | 所有 | 超时时间（秒） |\n| `max_tokens` | 所有 | 最大生成长度 |\n| `temperature` | 所有 | 采样温度 |\n| `top_p` | 所有 | 核采样参数 |\n| `request_timeout` | 所有 | 请求超时 |\n\n## 扩展开发\n\n如需添加新的LLM提供商，可按以下步骤扩展：\n\n1. 创建新文件如`src/hipporag/llm/custom_llm.py`\n2. 继承`LLMInterface`抽象基类\n3. 实现`_call`和`_batch_call`抽象方法\n4. 在模块`__init__.py`中导出新类\n\n```python\nfrom hipporag.llm.base import LLMInterface\n\nclass CustomLLM(LLMInterface):\n def _call(self, prompt, system_prompt, keyword):\n # 实现具体的模型调用逻辑\n pass\n \n def _batch_call(self, prompts, system_prompts, keywords):\n # 实现批量调用逻辑\n pass\n```\n\n## 注意事项\n\n- 所有LLM实现类都继承自`LiteLLM`，其底层封装了lite-llm库以提供统一的调用方式\n- `temperature`和`top_p`参数影响生成多样性，通常RAG场景使用`temperature=0.0`以获得确定性结果\n- vLLM和Transformers适合需要数据隐私或控制推理环境的场景\n- AWS Bedrock需要正确配置AWS凭证和区域信息\n\n---\n\n\n\n## Embedding模型集成\n\n### 相关页面\n\n相关主题：[系统架构设计](#p3), [LLM模型集成](#p5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/embedding_model/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/base.py)\n- [src/hipporag/embedding_model/NVEmbedV2.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/NVEmbedV2.py)\n- [src/hipporag/embedding_model/GritLM.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/GritLM.py)\n- [src/hipporag/embedding_model/Transformers.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/Transformers.py)\n- [src/hipporag/embedding_model/VLLM.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/VLLM.py)\n- [src/hipporag/embedding_model/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/__init__.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)\n \n\n# Embedding模型集成\n\n## 概述\n\nHippoRAG的Embedding模型集成模块负责将文本转换为高维向量表示，以便在知识图谱构建和检索过程中进行语义相似度计算。该模块采用策略模式设计，通过抽象基类 `BaseEmbeddingModel` 定义统一接口，支持多种嵌入模型后端的灵活切换。资料来源：[src/hipporag/embedding_model/base.py:1-20]()\n\nEmbedding模型在HippoRAG系统中承担三项核心职责：\n\n- **文档编码**：将输入文档、段落和实体转换为向量表示，用于构建向量存储\n- **查询编码**：将用户查询转换为向量，以便进行语义检索\n- **KNN检索**：基于向量相似度进行最近邻搜索，支持同义词边构建和实体链接\n\n## 架构设计\n\n### 模块结构\n\n```\n📦 src/hipporag/embedding_model/\n├── __init__.py # 模型选择器，提供 get_embedding_model 函数\n├── base.py # 基类 BaseEmbeddingModel 和 EmbeddingConfig\n├── NVEmbedV2.py # NVIDIA NV-Embed-v2 模型实现\n├── GritLM.py # GritLM 模型实现\n├── Transformers.py # HuggingFace Transformers 模型实现\n└── VLLM.py # vLLM 服务嵌入模型实现\n```\n\n资料来源：[README.md - Code Structure]()\n\n### 类层次结构\n\n```mermaid\ngraph TD\n A[BaseEmbeddingModel] --> B[NVEmbedV2Model]\n A --> C[GritLMModel]\n A --> D[TransformersEmbeddingModel]\n A --> E[VLLMEmbeddingModel]\n \n F[HippoRAG] --> A\n G[EmbeddingStore] --> A\n```\n\n### 嵌入模型选择流程\n\n```mermaid\ngraph TD\n A[初始化 HippoRAG] --> B{embedding_model_name 前缀判断}\n B -->|\"nvidia/NV-Embed\"| C[NVEmbedV2Model]\n B -->|\"GritLM/\"| D[GritLMModel]\n B -->|\"Transformers/\"| E[TransformersEmbeddingModel]\n B -->|\"VLLM/\"| F[VLLMEmbeddingModel]\n B -->|其他| G[默认模型]\n \n C --> H[加载本地模型]\n D --> I[加载 GritLM]\n E --> J[加载 SentenceTransformer]\n F --> K[连接 vLLM 服务]\n```\n\n## 基础抽象类\n\n### BaseEmbeddingModel\n\n`BaseEmbeddingModel` 是所有嵌入模型的基类，定义了统一的接口规范。所有具体实现必须继承此类并实现核心方法。\n\n#### 核心属性\n\n| 属性名 | 类型 | 说明 |\n|--------|------|------|\n| `embedding_type` | str | 嵌入向量的数据类型标识，如 \"float\" |\n| `batch_size` | int | 默认批处理大小 |\n| `search_query_instr` | set | 查询指令集合，用于区分不同检索任务 |\n\n资料来源：[src/hipporag/embedding_model/base.py:1-30]()\n\n#### 核心方法\n\n| 方法名 | 参数 | 返回值 | 说明 |\n|--------|------|--------|------|\n| `encode` | texts: List[str] | np.array | 单次调用编码单个文本批次 |\n| `batch_encode` | texts: List[str], **kwargs | np.array | 分批编码大量文本，支持进度显示 |\n\n```python\nclass BaseEmbeddingModel(ABC):\n @abstractmethod\n def encode(self, texts: List[str]) -> np.array:\n \"\"\"将文本列表编码为嵌入向量\"\"\"\n pass\n \n def batch_encode(self, texts: List[str], **kwargs) -> np.array:\n \"\"\"分批编码，默认实现为循环调用 encode\"\"\"\n pass\n```\n\n## 支持的嵌入模型\n\n### 1. NV-Embed-v2\n\nNVIDIA的NV-Embed-v2是高性能嵌入模型，支持本地部署和量化推理。\n\n#### 初始化参数\n\n| 参数 | 来源配置 | 默认值 | 说明 |\n|------|----------|--------|------|\n| `global_config` | 必填 | - | 全局配置对象 |\n| `embedding_model_name` | 必填 | - | 模型名称，格式为 \"nvidia/NV-Embed-v2\" |\n\n#### 关键实现\n\n```python\nclass NVEmbedV2Model(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name\n self.model = AutoModel.from_pretrained(\n self.model_id,\n trust_remote_code=True,\n device_map=\"cuda\"\n )\n self.batch_size = 32\n```\n\n#### 特性\n\n- 支持 HuggingFace `AutoModel` 接口\n- 自动设备映射到 CUDA\n- 使用 `trust_remote_code=True` 加载自定义模型代码\n- 支持批处理编码，默认批次大小为32\n\n资料来源：[src/hipporag/embedding_model/NVEmbedV2.py:1-40]()\n\n### 2. GritLM\n\nGritLM 是专门用于检索和生成的统一嵌入模型。\n\n#### 初始化参数\n\n| 参数 | 来源配置 | 默认值 | 说明 |\n|------|----------|--------|------|\n| `global_config` | 必填 | - | 全局配置对象 |\n| `embedding_model_name` | 必填 | - | 模型名称，格式为 \"GritLM/...\" |\n\n#### 关键实现\n\n```python\nclass GritLMModel(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name[len(\"GritLM/\"):]\n self.model = GritLM(model_id=self.model_id)\n```\n\n#### 特性\n\n- 使用 `gritlm` 库实现\n- 支持检索和生成双重任务\n- 继承 GritLM 库的默认优化设置\n\n资料来源：[src/hipporag/embedding_model/GritLM.py:1-25]()\n\n### 3. Transformers (HuggingFace)\n\n通过 `SentenceTransformer` 支持所有 HuggingFace 模型。\n\n#### 初始化参数\n\n| 参数 | 来源配置 | 默认值 | 说明 |\n|------|----------|--------|------|\n| `global_config` | 必填 | - | 全局配置对象 |\n| `embedding_model_name` | 必填 | - | 模型名称，格式为 \"Transformers/模型ID\" |\n\n#### 关键实现\n\n```python\nclass TransformersEmbeddingModel(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name[len(\"Transformers/\"):]\n self.model = SentenceTransformer(\n self.model_id,\n device=\"cuda\" if torch.cuda.is_available() else \"cpu\"\n )\n self.batch_size = 64\n```\n\n#### 特性\n\n- 使用 `sentence-transformers` 库\n- 自动检测 CUDA 可用性\n- 默认批处理大小为64\n- 支持数千种 SentenceTransformer 模型\n\n资料来源：[src/hipporag/embedding_model/Transformers.py:1-30]()\n\n### 4. VLLM (远程服务)\n\n支持连接 OpenAI 兼容的 vLLM 嵌入服务端点。\n\n#### 初始化参数\n\n| 参数 | 来源配置 | 默认值 | 说明 |\n|------|----------|--------|------|\n| `global_config` | 必填 | - | 全局配置对象，需包含 `embedding_base_url` |\n| `embedding_model_name` | 必填 | - | 模型名称，格式为 \"VLLM/模型名\" |\n\n#### 关键实现\n\n```python\nclass VLLMEmbeddingModel(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name[len(\"VLLM/\"):]\n self.url = global_config.embedding_base_url\n \n def call_model(self, input_text):\n payload = {\n \"model\": self.model_id,\n \"input\": input_text,\n }\n response = requests.post(self.url, json=payload)\n return np.array([response[\"data\"][i][\"embedding\"] \n for i in range(len(response[\"data\"]))])\n```\n\n#### 特性\n\n- 通过 REST API 连接远程服务\n- 使用 OpenAI 兼容的 `/v1/embeddings` 接口\n- 支持自定义服务端点配置\n\n资料来源：[src/hipporag/embedding_model/VLLM.py:1-40]()\n\n## 配置参数\n\n嵌入模型相关的配置通过 `BaseConfig` 类管理。\n\n### 嵌入模型配置项\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `embedding_batch_size` | int | 16 | 调用嵌入模型的批次大小 |\n| `embedding_return_as_normalized` | bool | True | 是否返回归一化嵌入向量 |\n| `embedding_max_seq_len` | int | 2048 | 嵌入模型的最大序列长度 |\n| `embedding_model_dtype` | str | \"auto\" | 数据类型，可选 float16/float32/bfloat16/auto |\n| `synonymy_edge_topk` | int | 2047 | 构建同义词边时的 KNN 检索数量 |\n| `synonymy_edge_query_batch_size` | int | 1000 | 同义词边构建的查询批次大小 |\n| `synonymy_edge_key_batch_size` | int | 10000 | 同义词边构建的键批次大小 |\n| `synonymy_edge_sim_threshold` | float | 0.8 | 同义词相似度阈值 |\n\n资料来源：[src/hipporag/utils/config_utils.py:1-50]()\n\n## 使用方式\n\n### 模型选择器\n\n通过前缀自动选择对应的嵌入模型实现：\n\n```python\nfrom hipporag.embedding_model import get_embedding_model\n\n# 获取嵌入模型实例\nembedding_model = get_embedding_model(\n global_config=config,\n embedding_model_name=\"nvidia/NV-Embed-v2\"\n)\n```\n\n#### 前缀映射表\n\n| 前缀 | 模型类 | 用途 |\n|------|--------|------|\n| `nvidia/NV-Embed` | NVEmbedV2Model | NVIDIA 高性能嵌入 |\n| `GritLM/` | GritLMModel | 检索生成统一模型 |\n| `Transformers/` | TransformersEmbeddingModel | HuggingFace 模型 |\n| `VLLM/` | VLLMEmbeddingModel | vLLM 远程服务 |\n\n资料来源：[src/hipporag/embedding_model/__init__.py:1-30]()\n\n### 完整使用示例\n\n#### OpenAI 兼容模型\n\n```python\nfrom hipporag import HippoRAG\n\nhipporag = HippoRAG(\n save_dir=\"outputs\",\n llm_model_name=\"gpt-4o-mini\",\n llm_base_url=\"https://api.openai.com/v1\",\n embedding_model_name=\"nvidia/NV-Embed-v2\",\n embedding_base_url=\"https://api.openai.com/v1\"\n)\n\n# 执行索引和检索\nhipporag.index(docs=documents)\nresults = hipporag.rag_qa(queries=queries)\n```\n\n#### 本地 vLLM 模型\n\n```bash\n# 启动 vLLM 嵌入服务\nvllm serve nvidia/NV-Embed-v2 --port 8080\n```\n\n```python\nhipporag = HippoRAG(\n save_dir=\"outputs\",\n llm_model_name=\"meta-llama/Llama-3.1-8B-Instruct\",\n llm_base_url=\"http://localhost:6578/v1\",\n embedding_model_name=\"VLLM/nvidia/NV-Embed-v2\",\n embedding_base_url=\"http://localhost:8080/v1/embeddings\"\n)\n```\n\n## 与HippoRAG集成\n\n### 初始化流程\n\n```mermaid\nsequenceDiagram\n participant User\n participant HippoRAG\n participant EmbeddingModel\n participant EmbeddingStore\n \n User->>HippoRAG: __init__(embedding_model_name)\n HippoRAG->>EmbeddingModel: get_embedding_model()\n HippoRAG->>EmbeddingStore: 创建向量存储\n EmbeddingStore->>EmbeddingModel: 关联嵌入模型\n```\n\n### 在索引过程中的作用\n\n1. **文档编码**：将原始文档分块后，使用嵌入模型编码为向量\n2. **实体编码**：从OpenIE提取的实体编码为向量\n3. **事实编码**：从OpenIE提取的事实三元组编码为向量\n4. **KNN检索**：基于向量相似度构建知识图谱的同义词边\n\n资料来源：[src/hipporag/HippoRAG.py:1-50]()\n\n## 依赖组件\n\n### Python包依赖\n\n| 包名 | 版本 | 用途 |\n|------|------|------|\n| `torch` | 2.5.1 | 张量计算和CUDA支持 |\n| `transformers` | 4.45.2 | 模型加载和推理 |\n| `sentence-transformers` | - | SentenceTransformer模型支持 |\n| `gritlm` | 1.0.2 | GritLM模型支持 |\n| `vllm` | 0.6.6.post1 | vLLM服务端支持 |\n| `numpy` | - | 向量数据处理 |\n\n资料来源：[setup.py:1-30]()\n\n## 扩展开发\n\n### 添加新的嵌入模型\n\n1. 继承 `BaseEmbeddingModel` 基类\n2. 实现 `encode()` 方法\n3. 在 `__init__.py` 的 `get_embedding_model()` 中添加模型选择逻辑\n\n```python\n# src/hipporag/embedding_model/CustomModel.py\nfrom .base import BaseEmbeddingModel\n\nclass CustomEmbeddingModel(BaseEmbeddingModel):\n def __init__(self, global_config, embedding_model_name):\n super().__init__(global_config)\n self.model_id = embedding_model_name\n # 初始化自定义模型\n \n def encode(self, texts):\n # 实现编码逻辑\n pass\n```\n\n```python\n# src/hipporag/embedding_model/__init__.py\ndef get_embedding_model(global_config, embedding_model_name):\n if embedding_model_name.startswith(\"CustomModel/\"):\n return CustomEmbeddingModel(global_config, embedding_model_name)\n # ... 其他模型\n```\n\n## 性能优化建议\n\n| 优化项 | 说明 |\n|--------|------|\n| 批处理大小 | 根据GPU显存调整 `embedding_batch_size`，默认16 |\n| 序列长度 | 确保 `embedding_max_seq_len` 匹配模型能力 |\n| 归一化 | 启用 `embedding_return_as_normalized=True` 可加速相似度计算 |\n| 混合部署 | 将嵌入模型与LLM部署在不同GPU上避免显存竞争 |\n\n资料来源：[README.md - Quick Start]()\n\n---\n\n\n\n## OpenIE信息抽取\n\n### 相关页面\n\n相关主题：[知识图谱构建](#p4), [Prompt模板管理](#p8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/information_extraction/openie_openai_gpt.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/information_extraction/openie_openai_gpt.py)\n- [src/hipporag/information_extraction/openie_vllm_offline.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/information_extraction/openie_vllm_offline.py)\n- [src/hipporag/information_extraction/openie_transformers_offline.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/information_extraction/openie_transformers_offline.py)\n- [src/hipporag/prompts/templates/triple_extraction.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/prompts/templates/triple_extraction.py)\n- [src/hipporag/prompts/templates/ner.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/prompts/templates/ner.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n \n\n# OpenIE信息抽取\n\n## 概述\n\nOpenIE（Open Information Extraction，开放信息抽取）是HippoRAG框架中的核心组件，负责从文本语料中自动提取结构化的知识三元组。这些三元组构成了HippoRAG知识图谱的基础节点和边，使得大型语言模型能够识别和利用文档之间的语义关联，从而显著提升检索增强生成（RAG）的效果。\n\n在HippoRAG系统中，OpenIE信息抽取的主要职责包括：\n\n- **三元组抽取**：从原始文本中提取形如`(主语, 谓词, 宾语)`的结构化知识表示\n- **实体识别**：识别文本中的命名实体及其类型\n- **知识图谱构建**：为后续的图检索和个性化PageRank算法提供基础结构\n\nHippoRAG支持多种OpenIE运行模式，开发者可根据实际需求选择使用在线API（如OpenAI GPT）或离线部署（如vLLM、Transformers）的方式进行信息抽取。资料来源：[src/hipporag/utils/config_utils.py:28-35]()\n\n## 架构设计\n\n### 组件结构\n\nHippoRAG的OpenIE信息抽取模块采用模块化设计，主要包含以下核心组件：\n\n```mermaid\ngraph TD\n A[文本输入] --> B[文本预处理]\n B --> C[OpenIE信息抽取模块]\n C --> D{运行模式选择}\n D -->|online| E[OpenAI GPT抽取器]\n D -->|offline| F[vLLM离线抽取器]\n D -->|Transformers-offline| G[Transformers离线抽取器]\n E --> H[三元组输出]\n F --> H\n G --> H\n H --> I[知识图谱构建]\n```\n\n### 文件组织\n\n```\nsrc/hipporag/\n├── information_extraction/ # OpenIE信息抽取模块\n│ ├── __init__.py # 模块初始化与导出\n│ ├── base.py # 基类定义\n│ ├── openie_openai_gpt.py # OpenAI GPT在线抽取实现\n│ ├── openie_vllm_offline.py # vLLM离线批量抽取实现\n│ └── openie_transformers_offline.py # Transformers离线抽取实现\n└── prompts/\n └── templates/\n ├── triple_extraction.py # 三元组抽取提示模板\n └── ner.py # 命名实体识别提示模板\n```\n\n## 运行模式\n\nHippoRAG的OpenIE模块支持三种运行模式，通过配置参数`openie_mode`进行选择：\n\n| 模式 | 配置值 | 描述 | 适用场景 |\n|------|--------|------|----------|\n| 在线模式 | `online` | 使用OpenAI GPT API进行实时抽取 | 快速原型开发、小规模数据集 |\n| vLLM离线模式 | `offline` | 使用本地部署的vLLM服务进行批量抽取 | 大规模生产环境、降低成本 |\n| Transformers离线模式 | `Transformers-offline` | 使用本地Transformers模型进行抽取 | 完全离线环境、特定模型需求 |\n\n### 在线模式（OpenAI GPT）\n\n在线模式使用OpenAI GPT模型进行信息抽取，是默认的运行模式。该模式配置简单，适合快速验证和小型数据集场景。\n\n```python\n# 配置示例\nconfig = BaseConfig(\n openie_mode='online',\n information_extraction_model_name='openie_openai_gpt'\n)\n```\n\n主要特点：\n\n- 配置简便，无需本地部署模型\n- 依赖OpenAI API，需要有效的API密钥\n- 适合开发和测试阶段\n- 支持的模型：`gpt-4o`、`gpt-4o-mini`等\n\n资料来源：[src/hipporag/utils/config_utils.py:28-35]()\n\n### vLLM离线模式\n\nvLLM离线模式使用本地部署的vLLM推理服务进行批量信息抽取，是生产环境推荐的方式。\n\n```python\n# 配置示例\nconfig = BaseConfig(\n openie_mode='offline',\n information_extraction_model_name='openie_openai_gpt' # 使用OpenIE格式\n)\n```\n\n**部署要求：**\n\n```bash\n# 启动vLLM服务\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nvllm serve meta-llama/Llama-3.3-70B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n主要优势：\n\n- **成本效益**：无需支付API调用费用\n- **性能优化**：支持张量并行，加速批量处理\n- **隐私保护**：数据完全在本地处理\n- **可扩展性**：支持更大规模的语料处理\n\n资料来源：[README.md - Local Deployment (vLLM)]()\n\n### Transformers离线模式\n\n该模式使用HuggingFace Transformers库直接加载模型进行推理，适合完全离线或需要使用特定模型的场景。\n\n```python\n# 配置示例\nconfig = BaseConfig(\n openie_mode='Transformers-offline',\n information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct'\n)\n```\n\n使用示例（来自`test_transformers.py`）：\n\n```python\nglobal_config = BaseConfig(\n openie_mode='Transformers-offline',\n information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct'\n)\n\nhipporag = HippoRAG(\n global_config,\n save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name,\n)\n```\n\n## 抽取流程\n\n### 整体工作流\n\n```mermaid\ngraph LR\n A[文档集合] --> B[文档分块
Chunking]\n B --> C[分块文本]\n C --> D{openie_mode}\n D -->|online| E[调用OpenAI API]\n D -->|offline| F[调用vLLM服务]\n D -->|Transformers| G[本地模型推理]\n E --> H[三元组解析]\n F --> H\n G --> H\n H --> I[结果存储]\n I --> J[知识图谱构建]\n```\n\n### 三元组抽取\n\n三元组抽取是OpenIE的核心功能，将非结构化文本转换为`(主语, 谓词, 宾语)`形式的知识表示。\n\n**抽取提示模板**（`triple_extraction.py`）：\n\n系统使用精心设计的提示模板引导语言模型输出结构化的三元组信息。提示模板通常包含：\n\n- 抽取任务的明确定义\n- 输出格式规范（如JSON格式）\n- 示例输入输出对\n- 边界情况处理指南\n\n**输出格式示例：**\n\n```json\n[\n {\n \"subject\": \"Oliver Badman\",\n \"predicate\": \"is a\",\n \"object\": \"politician\"\n },\n {\n \"subject\": \"The prince\",\n \"predicate\": \"used\",\n \"object\": \"the lost glass slipper\"\n }\n]\n```\n\n### 命名实体识别\n\nNER模块（`ner.py`）负责识别文本中的命名实体，包括人名、地点、组织等。识别的实体用于：\n\n- 增强知识图谱的节点信息\n- 辅助实体链接和消歧\n- 提供更丰富的检索特征\n\n## 配置参数\n\n### 全局配置项\n\nHippoRAG的`BaseConfig`类提供了丰富的OpenIE相关配置选项：\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `information_extraction_model_name` | Literal | `openie_openai_gpt` | 信息抽取模型类名 |\n| `openie_mode` | Literal | `online` | OpenIE运行模式：`online`、`offline`或`Transformers-offline` |\n| `skip_graph` | bool | `False` | 是否跳过图构建（首次离线索引时设为True） |\n| `save_openie` | bool | `True` | 是否保存OpenIE结果到磁盘 |\n\n### 高级配置\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|--------|------|--------|------|\n| `preprocess_encoder_name` | str | `gpt-4o` | 预处理编码器名称（用于文档分块） |\n| `preprocess_chunk_max_token_size` | int | `None` | 每个chunk的最大token数，`None`表示整个文档作为单一chunk |\n| `preprocess_chunk_overlap_token_size` | int | `128` | 相邻chunk之间的重叠token数 |\n\n资料来源：[src/hipporag/utils/config_utils.py:28-72]()\n\n## 使用指南\n\n### 快速开始\n\n#### 1. 环境配置\n\n```bash\n# 设置环境变量\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=\n\n# 激活环境\nconda activate hipporag\n```\n\n#### 2. 基础使用示例\n\n```python\nfrom hipporag import HippoRAG\n\n# 准备文档\ndocs = [\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"\n]\n\n# 初始化HippoRAG\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# 执行索引（包括OpenIE抽取）\nhipporag.index(docs=docs)\n\n# 执行问答检索\nqueries = [\"What is George Rankin's occupation?\"]\ngold_docs = [[\"George Rankin is a politician.\"]]\nanswers = [[\"Politician\"]]\n\nresults = hipporag.rag_qa(\n queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers\n)\n```\n\n### vLLM离线模式完整流程\n\n#### 步骤1：启动vLLM服务\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nvllm serve meta-llama/Llama-3.3-70B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n#### 步骤2：运行主程序\n\n```bash\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=''\n\npython main.py \\\n --dataset sample \\\n --llm_name meta-llama/Llama-3.3-70B-Instruct \\\n --openie_mode offline \\\n --skip_graph\n```\n\n#### 步骤3：完成索引和问答\n\n首次运行使用`--skip_graph`参数后，OpenIE结果会保存到文件。第二次运行时去掉该参数即可完成图构建：\n\n```bash\npython main.py \\\n --dataset sample \\\n --llm_name meta-llama/Llama-3.3-70B-Instruct \\\n --openie_mode offline\n```\n\n资料来源：[README.md - Reproducing our Experiments]()\n\n### 调试技巧\n\n1. **使用小数据集调试**：项目提供的`/reproduce/dataset/sample.json`是专门用于调试的小数据集\n\n2. **清理缓存**：重新运行实验时，记得清除保存的文件：\n ```bash\n rm reproduce/dataset/openie_results/openie_sample_results_*.json\n rm -rf outputs/sample/\n ```\n\n3. **vLLM离线模式调试**：当遇到问题时，将`hipporag/llm/vllm_offline.py`中的`tensor_parallel_size`设为1\n\n4. **查看保存的OpenIE结果**：OpenIE结果默认保存，可直接检查输出格式是否正确\n\n## 输出与存储\n\n### OpenIE结果保存\n\nOpenIE抽取结果默认保存到指定目录，文件命名格式包含模型和数据集信息：\n\n```\noutputs//_/openie_results/\n└── openie__results_.json\n```\n\n### 结果格式\n\n```json\n{\n \"doc_id\": 0,\n \"doc_text\": \"Oliver Badman is a politician.\",\n \"triples\": [\n {\n \"subject\": \"Oliver Badman\",\n \"predicate\": \"is a\",\n \"object\": \"politician\"\n }\n ],\n \"entities\": [\n {\"text\": \"Oliver Badman\", \"type\": \"PERSON\"}\n ]\n}\n```\n\n### 与知识图谱的集成\n\nOpenIE抽取的三元组直接用于构建HippoRAG的知识图谱：\n\n```mermaid\ngraph LR\n A[三元组] --> B[实体节点]\n A --> C[关系边]\n B --> D[知识图谱]\n C --> D\n D --> E[个性化PageRank检索]\n E --> F[LLM问答生成]\n```\n\n## 性能优化建议\n\n### 1. 批量处理\n\n离线模式支持批量调用，可显著提升处理速度：\n\n```python\n# 批量文档索引\nhipporag.index(docs=large_documents_list)\n```\n\n### 2. GPU资源分配\n\n- **vLLM服务**：分配专用GPU（如0,1）\n- **主程序**：使用另一组GPU（如2,3）\n- 通过`CUDA_VISIBLE_DEVICES`环境变量控制\n\n### 3. 内存优化\n\n```bash\n# 调整最大序列长度\n--max_model_len 4096\n\n# 调整GPU内存利用率\n--gpu-memory-utilization 0.95\n```\n\n### 4. 并行配置\n\n```bash\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\n```\n\n## 常见问题\n\n### Q1: 首次运行vLLM离线模式需要设置什么参数？\n\n需要设置`--skip_graph`参数，因为首次运行时图尚未构建：\n\n```bash\npython main.py --openie_mode offline --skip_graph\n```\n\n### Q2: 如何切换不同的OpenIE模型？\n\n通过修改`information_extraction_model_name`配置：\n\n```python\n# 使用OpenAI GPT\nconfig = BaseConfig(information_extraction_model_name='openie_openai_gpt')\n\n# 使用Transformers模型\nconfig = BaseConfig(\n information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct',\n openie_mode='Transformers-offline'\n)\n```\n\n### Q3: OpenIE结果支持增量更新吗？\n\n是的，HippoRAG支持增量更新。删除文档后重新索引，已保存的OpenIE结果会被重用。\n\n### Q4: 如何处理长文档？\n\n对于过长的文档，建议先进行分块处理：\n\n```python\nconfig = BaseConfig(\n preprocess_chunk_max_token_size=512,\n preprocess_chunk_overlap_token_size=64\n)\n```\n\n## 参考链接\n\n- HippoRAG官方仓库：https://github.com/OSU-NLP-Group/HippoRAG\n- HippoRAG 2论文：https://arxiv.org/abs/2502.14802\n- HippoRAG 1论文：https://arxiv.org/abs/2405.14831\n- vLLM文档：https://docs.vllm.ai/\n\n---\n\n\n\n## Prompt模板管理\n\n### 相关页面\n\n相关主题：[OpenIE信息抽取](#p7), [LLM模型集成](#p5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/prompts/templates/README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/prompts/templates/README.md)\n- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)\n- [src/hipporag/StandardRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/StandardRAG.py)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n \n\n# Prompt模板管理\n\n## 概述\n\nHippoRAG框架中的Prompt模板管理模块负责组织和调用系统中各类LLM推理所需的提示词模板。该模块位于 `src/hipporag/prompts/` 目录下，采用模块化的设计思想，将不同功能场景的提示词模板分别存放于独立文件中，便于维护和扩展。\n\nPrompt模板管理系统的核心作用包括：\n\n- **模板存储与加载**：通过文件系统组织提示词模板，支持动态加载\n- **模板渲染**：使用 `prompt_template_manager` 将占位符替换为实际数据\n- **数据集适配**：根据不同数据集选择对应的提示词模板\n- **统一接口**：为HippoRAG和StandardRAG等组件提供一致的模板访问方式\n\n资料来源：[src/hipporag/prompts/templates/README.md:1-18]()\n\n## 目录结构\n\n```\nsrc/hipporag/prompts/\n├── __init__.py\n├── prompt_template_manager.py # 模板管理器核心实现\n├── linking.py # 图谱链接相关提示词\n├── filter_default_prompt.py # 过滤模块默认提示词\n├── templates/\n│ ├── __init__.py\n│ ├── rag_qa_musique.py # MuSiQue数据集QA模板\n│ ├── ircot_hotpotqa.py # HotpotQA多跳问答模板\n│ └── ... # 其他数据集模板\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## 模板定义规范\n\n### 文件命名规则\n\n模板文件夹 `templates/` 被作为 `hipporag` 项目下的子模块处理。每个 `*.py` 文件（除 `__init__.py` 外）对应一个提示词模板，文件名（不含文件扩展名）将作为访问该模板的键名。\n\n| 规则 | 说明 |\n|------|------|\n| 文件扩展名 | 必须为 `.py` |\n| 排除文件 | `__init__.py` 不被视为模板 |\n| 命名规范 | 使用下划线连接，如 `rag_qa_musique.py` |\n| 访问键名 | 文件名去掉 `.py` 后缀，如 `rag_qa_musique` |\n\n资料来源：[src/hipporag/prompts/templates/README.md:5-8]()\n\n### 模板变量规范\n\n每个模板文件必须定义一个名为 `prompt_template` 的变量来存储提示词内容。该变量可以是以下三种形式之一：\n\n```python\n# 形式1: 字符串（支持 ${} 占位符）\nprompt_template = \"Question: ${question}\\nAnswer:\"\n\n# 形式2: Template对象实例\nfrom string import Template\nprompt_template = Template(\"Wikipedia Title: ${title}\\n\\n${text}\")\n\n# 形式3: 聊天历史格式（List[dict]）\nprompt_template = [\n {\"role\": \"system\", \"content\": \"You are a helpful assistant.\"},\n {\"role\": \"user\", \"content\": \"Question: ${question}\"}\n]\n```\n\n| 形式 | 数据类型 | 占位符格式 | 适用场景 |\n|------|----------|------------|----------|\n| 字符串 | `str` | `${variable}` | 简单模板 |\n| Template对象 | `Template` | `$variable` 或 `${variable}` | 需要转义的场景 |\n| 聊天历史 | `List[dict]` | `${variable}` | 多轮对话模板 |\n\n资料来源：[src/hipporag/prompts/templates/README.md:10-17]()\n\n## 模板渲染机制\n\n### PromptTemplateManager\n\n`PromptTemplateManager` 是模板系统的核心管理类，负责模板的加载、验证和渲染。\n\n#### 模板选择逻辑\n\nHippoRAG在执行检索和QA任务时，会根据当前数据集选择对应的提示词模板。核心逻辑如下：\n\n```python\nif self.prompt_template_manager.is_template_name_valid(name=f'rag_qa_{self.global_config.dataset}'):\n # 查找该数据集对应的自定义提示词\n prompt_dataset_name = self.global_config.dataset\nelse:\n # 数据集尚未定义自定义模板，使用MuSiQue的通用模板作为后备\n logger.debug(\n f\"rag_qa_{self.global_config.dataset} does not have a customized prompt template. \"\n f\"Using MUSIQUE's prompt template instead.\")\n prompt_dataset_name = 'musique'\n```\n\n资料来源：[src/hipporag/HippoRAG.py:1-20]()\n\n#### 模板渲染流程\n\n```mermaid\ngraph TD\n A[开始渲染] --> B{数据集模板是否存在?}\n B -->|是| C[使用数据集特定模板]\n B -->|否| D[使用musique通用模板]\n C --> E[调用render方法]\n D --> E\n E --> F[替换prompt_user占位符]\n F --> G[返回渲染后的消息]\n```\n\n### 模板渲染示例\n\nHippoRAG在QA阶段将检索到的文档传入模板进行渲染：\n\n```python\nprompt_user = ''\nfor passage in retrieved_passages:\n prompt_user += f'Wikipedia Title: {passage}\\n\\n'\nprompt_user += 'Question: ' + query_solution.question + '\\nThought: '\n\nall_qa_messages.append(\n self.prompt_template_manager.render(\n name=f'rag_qa_{prompt_dataset_name}', \n prompt_user=prompt_user\n )\n)\n```\n\n资料来源：[src/hipporag/HippoRAG.py:1-15]()\n\n## 预置模板\n\n### MuSiQue数据集模板\n\n`rag_qa_musique.py` 是HippoRAG的默认提示词模板，用于多跳问答场景。\n\n```python\nprompt_template = \"\"\"Given the following Wikipedia passages, ...\n\nThought: The question asks about ...\nWe need to find passages about ...\n...\n\nQuestion: {question}\nThought: \"\"\"\n```\n\n该模板采用Chain-of-Thought（思维链）风格，引导LLM逐步推理多跳问题。\n\n资料来源：[src/hipporag/prompts/templates/rag_qa_musique.py]()\n\n### HotpotQA模板\n\n`ircot_hotpotqa.py` 实现基于IRCoT（Iterated Retrieval Chain-of-Thought）的提示词模板，适用于HotpotQA双跳问答数据集。\n\n资料来源：[src/hipporag/prompts/templates/ircot_hotpotqa.py]()\n\n## 配置参数\n\nHippoRAG通过 `BaseConfig` 类管理模板相关的配置参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `dataset` | `str` | `None` | 当前数据集名称，用于选择对应模板 |\n| `max_qa_steps` | `int` | `1` | 单问题最大迭代推理步数 |\n| `qa_top_k` | `int` | `5` | 输入QA模型的文档数量 |\n\n```python\n# QA特定配置\nmax_qa_steps: int = field(\n default=1,\n metadata={\"help\": \"For answering a single question, the max steps that we use to interleave retrieval and reasoning.\"}\n)\nqa_top_k: int = field(\n default=5,\n metadata={\"help\": \"Feeding top k documents to the QA model for reading.\"}\n)\n```\n\n资料来源：[src/hipporag/utils/config_utils.py:1-15]()\n\n## 使用示例\n\n### 基本使用流程\n\n```python\nfrom hipporag import HippoRAG\n\n# 初始化HippoRAG（会自动加载模板管理器）\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# 索引文档\nhipporag.index(docs=documents)\n\n# 执行QA（自动使用对应数据集的模板）\nresults = hipporag.rag_qa(\n queries=questions,\n gold_docs=gold_documents,\n gold_answers=expected_answers\n)\n```\n\n### 自定义模板\n\n如需为新数据集添加模板，需在 `src/hipporag/prompts/templates/` 目录下创建新文件：\n\n1. 创建 `rag_qa_your_dataset.py`\n2. 定义 `prompt_template` 变量\n3. 使用 `${}` 占位符标记需替换的位置\n\n```python\n# rag_qa_your_dataset.py\nprompt_template = \"\"\"Based on the following context...\n\nContext: {prompt_user}\n\nPlease answer the question based on the context.\"\"\"\n```\n\n创建后，系统会自动识别并可使用 `rag_qa_your_dataset` 作为模板名称。\n\n资料来源：[src/hipporag/prompts/templates/README.md:5-12]()\n\n## 与其他模块的集成\n\n### HippoRAG集成\n\n`HippoRAG` 类在执行 `rag_qa` 方法时调用模板管理器：\n\n```python\n# 位置: src/hipporag/HippoRAG.py\nall_qa_messages.append(\n self.prompt_template_manager.render(\n name=f'rag_qa_{prompt_dataset_name}', \n prompt_user=prompt_user\n )\n)\n```\n\n### StandardRAG集成\n\n`StandardRAG` 类使用完全相同的模板管理逻辑：\n\n```python\n# 位置: src/hipporag/StandardRAG.py\nall_qa_messages.append(\n self.prompt_template_manager.render(\n name=f'rag_qa_{prompt_dataset_name}', \n prompt_user=prompt_user\n )\n)\n```\n\n两者的模板选择和渲染机制保持一致，确保不同RAG变体之间的行为统一。\n\n资料来源：[src/hipporag/StandardRAG.py:1-15]()\n\n## 总结\n\nHippoRAG的Prompt模板管理系统具有以下特点：\n\n| 特性 | 描述 |\n|------|------|\n| **模块化设计** | 模板按数据集组织，便于维护和扩展 |\n| **灵活格式** | 支持字符串、Template对象和聊天历史三种格式 |\n| **自动回退** | 未知数据集自动回退到MuSiQue通用模板 |\n| **统一接口** | 为HippoRAG和StandardRAG提供一致的模板访问 |\n| **易于扩展** | 仅需创建新的 `.py` 文件即可添加模板 |\n\n该设计使得HippoRAG能够优雅地处理不同数据集的提示词需求，同时保持代码的简洁性和可维护性。\n\n---\n\n\n\n## 实验复现指南\n\n### 相关页面\n\n相关主题：[快速入门指南](#p2), [评估与测试](#p10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [main_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_azure.py)\n- [main_dpr.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_dpr.py)\n- [reproduce/README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/reproduce/README.md)\n- [reproduce/dataset/sample_corpus.json](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/reproduce/dataset/sample_corpus.json)\n \n\n# 实验复现指南\n\n本页面详细说明如何基于 HippoRAG 仓库复现论文中的实验结果。指南涵盖环境配置、数据准备、索引构建、检索与问答等完整流程。\n\n## 1. 环境准备\n\n### 1.1 系统要求\n\nHippoRAG 对运行环境有明确的依赖要求，需确保满足以下条件：\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | >= 3.10 | 必须使用 Python 3.10 或更高版本 |\n| CUDA | 兼容 | 需要 GPU 支持进行模型推理 |\n| GPU 显存 | 视模型而定 | 建议多卡以支持大型模型 |\n\n### 1.2 依赖安装\n\n首先创建独立的 conda 环境并安装核心依赖：\n\n```bash\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install hipporag\n```\n\n资料来源：[README.md:1]()\n\n### 1.3 环境变量配置\n\n启动 HippoRAG 前需配置以下环境变量：\n\n```bash\n# GPU 配置\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\n\n# HuggingFace 模型缓存路径\nexport HF_HOME=\n\n# OpenAI API 密钥（使用 OpenAI 模型时必需）\nexport OPENAI_API_KEY=\n\n# 激活环境\nconda activate hipporag\n```\n\n资料来源：[README.md:1]()\n\n### 1.4 vLLM 本地部署环境\n\n如需使用本地 vLLM 部署，需额外配置：\n\n```bash\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n```\n\n## 2. 数据准备\n\n### 2.1 数据集来源\n\n实验所需数据集可从以下渠道获取：\n\n| 数据集类型 | 来源 | 说明 |\n|------------|------|------|\n| 预定义数据集 | `reproduce/dataset/` 目录 | 仓库已包含部分采样数据集 |\n| 完整数据集 | [HuggingFace HippoRAG_v2](https://huggingface.co/datasets/osunlp/HippoRAG_v2) | 包含完整的评估数据集 |\n| OpenIE 结果 | `outputs/musique/` 目录 | 已预处理的信息抽取结果 |\n\n资料来源：[README.md:1]()\n\n### 2.2 数据目录结构\n\n推荐将数据集统一放置在 `reproduce/dataset/` 目录下：\n\n```\nreproduce/\n└── dataset/\n ├── sample_corpus.json # 语料库文件\n ├── sample.json # 查询文件（含答案）\n └── _corpus.json\n```\n\n### 2.3 语料库 JSON 格式\n\n语料库文件需遵循特定的 JSON 数组格式：\n\n```json\n[\n {\n \"title\": \"FIRST PASSAGE TITLE\",\n \"text\": \"FIRST PASSAGE TEXT\",\n \"idx\": 0\n },\n {\n \"title\": \"SECOND PASSAGE TITLE\",\n \"text\": \"SECOND PASSAGE TEXT\",\n \"idx\": 1\n }\n]\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| title | string | 是 | 段落标题 |\n| text | string | 是 | 段落正文内容 |\n| idx | integer | 是 | 段落唯一索引 |\n\n资料来源：[reproduce/README.md]()\n\n### 2.4 查询 JSON 格式（可选）\n\n如需进行评估，需准备包含问题和标准答案的查询文件：\n\n```json\n[\n {\n \"id\": \"sample/question_1.json\",\n \"question\": \"QUESTION\",\n \"answer\": [\"ANSWER\"],\n \"answerable\": true,\n \"paragraphs\": [\n {\n \"title\": \"{FIRST SUPPORTING PASSAGE TITLE}\",\n \"text\": \"{FIRST SUPPORTING PASSAGE TEXT}\",\n \"is_supporting\": true,\n \"idx\": 0\n }\n ]\n }\n]\n```\n\n**字段说明：**\n\n| 字段 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| id | string | 是 | 问题唯一标识 |\n| question | string | 是 | 查询问题文本 |\n| answer | array | 是 | 标准答案列表 |\n| answerable | boolean | 是 | 问题是否可答 |\n| paragraphs | array | 是 | 支持段落列表 |\n\n### 2.5 长文本分块\n\n对于过长的段落，可能需要在 OpenIE 处理前进行分块：\n\n> 当准备数据时，可能需要对每个段落进行分块，因为较长的段落可能对 OpenIE 过程过于复杂。\n\n资料来源：[README.md:1]()\n\n## 3. 实验运行流程\n\n### 3.1 整体工作流\n\n```mermaid\ngraph TD\n A[准备数据集] --> B[配置环境变量]\n B --> C{选择模型部署方式}\n C -->|OpenAI| D[设置 API 配置]\n C -->|vLLM 本地| E[启动 vLLM 服务]\n D --> F[运行 main.py]\n E --> G[运行 main.py]\n F --> H[索引构建]\n G --> H\n H --> I[检索与问答]\n I --> J[输出评估结果]\n```\n\n### 3.2 命令行参数说明\n\n`main.py` 支持多种命令行参数配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| --dataset | string | 必需 | 数据集名称 |\n| --llm_name | string | 必需 | LLM 模型名称 |\n| --llm_base_url | string | 必需 | LLM API 端点 |\n| --embedding_name | string | 必需 | 嵌入模型名称 |\n| --openie_mode | string | 'gpt-4o-mini' | OpenIE 运行模式 |\n\n资料来源：[main.py:1]()\n\n### 3.3 配置类参数\n\nHippoRAG 使用 `BaseConfig` 类管理核心配置参数：\n\n| 参数 | 说明 | 默认值 |\n|------|------|--------|\n| graph_type | 图类型 | facts_and_sim_passage_node_unidirectional |\n| embedding_batch_size | 嵌入批处理大小 | 8 |\n| max_new_tokens | 最大生成 token 数 | None |\n| retrieval_top_k | 检索返回文档数 | 200 |\n| linking_top_k | 每步链接节点数 | 5 |\n| max_qa_steps | QA 最大推理步数 | 3 |\n| qa_top_k | QA 输入 top k 文档数 | 5 |\n| damping | PPR 算法阻尼因子 | 0.5 |\n\n资料来源：[src/hipporag/utils/config_utils.py:1]()\n\n## 4. 使用 OpenAI 模型\n\n### 4.1 快速启动流程\n\n使用 OpenAI 模型进行实验的标准流程：\n\n```bash\n# 设置数据集\ndataset=sample # 或其他数据集\n\n# 运行 OpenAI 模型\npython main.py \\\n --dataset $dataset \\\n --llm_base_url https://api.openai.com/v1 \\\n --llm_name gpt-4o-mini \\\n --embedding_name nvidia/NV-Embed-v2\n```\n\n资料来源：[README.md:1]()\n\n### 4.2 支持的 OpenAI 兼容模型\n\nHippoRAG 支持任何 OpenAI 兼容的 API 端点，包括：\n\n- GPT-4 系列模型\n- GPT-3.5 系列模型\n- Azure OpenAI 部署模型\n- 其他 OpenAI 兼容的第三方 API\n\n### 4.3 Azure OpenAI 部署\n\n使用 Azure 端点时需指定额外参数：\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name,\n azure_endpoint=\"https://[ENDPOINT NAME].openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2025-01-01-preview\",\n azure_embedding_endpoint=\"https://[ENDPOINT NAME].openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2023-05-15\"\n)\n```\n\n资料来源：[main_azure.py:1]()\n\n## 5. 使用 vLLM 本地部署\n\n### 5.1 vLLM 服务启动\n\nvLLM 提供了 OpenAI 兼容的本地推理服务，启动步骤如下：\n\n```bash\n# 使用指定 GPU 启动服务（留足显存给嵌入模型）\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\n# 启动模型服务\nvllm serve meta-llama/Llama-3.3-70B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n```\n\n**参数调整建议：**\n\n| 参数 | 说明 | 调整建议 |\n|------|------|----------|\n| tensor-parallel-size | 并行 GPU 数量 | 根据可用 GPU 调整 |\n| max_model_len | 最大模型上下文长度 | 根据显存调整，显存不足时减小 |\n| gpu-memory-utilization | GPU 显存利用率 | 默认为 0.95，OOM 时减小 |\n\n资料来源：[README.md:1]()\n\n### 5.2 运行主程序\n\nvLLM 服务启动后，使用另一组 GPU 运行主程序：\n\n```bash\n# 设置另一组 GPU\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\n\n# 运行实验\npython main.py \\\n --dataset $dataset \\\n --llm_base_url http://localhost:6578/v1 \\\n --llm_name meta-llama/Llama-3.3-70B-Instruct \\\n --embedding_name nvidia/NV-Embed-v2\n```\n\n资料来源：[README.md:1]()\n\n### 5.3 轻量级测试配置\n\n为节省测试成本，可使用较小的模型：\n\n```bash\n# 测试用 vLLM 启动\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n\n# 运行本地测试\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:1]()\n\n## 6. 测试验证\n\n### 6.1 OpenAI 模型测试\n\n验证环境配置正确性的快速测试：\n\n```bash\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n该测试成本可忽略不计，可用于验证基本功能。\n\n### 6.2 本地模型测试\n\n使用本地部署模型进行完整功能测试：\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\n# 启动 vLLM 服务后\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n### 6.3 测试覆盖范围\n\n测试脚本验证以下核心模块功能：\n\n- 索引构建（Indexing）\n- 图加载（Graph Loading）\n- 文档删除（Document Deletion）\n- 增量更新（Incremental Updates）\n\n资料来源：[README.md:1]()\n\n## 7. 完整示例代码\n\n### 7.1 基本使用流程\n\n以下代码展示了完整的 HippoRAG 使用流程：\n\n```python\nfrom hipporag import HippoRAG\n\n# 初始化配置\nsave_dir = 'outputs'\nllm_model_name = 'gpt-4o-mini'\nembedding_model_name = 'nvidia/NV-Embed-v2'\n\n# 创建实例\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name\n)\n\n# 索引文档\ndocs = [\"文档内容1\", \"文档内容2\", \"文档内容3\"]\nhipporag.index(docs=docs)\n\n# 执行检索与问答\nqueries = [\"查询问题1\", \"查询问题2\"]\ngold_docs = [[\"相关文档1\"], [\"相关文档2\"]]\nanswers = [[\"答案1\"], [\"答案2\"]]\n\nresults = hipporag.rag_qa(\n queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers\n)\n```\n\n### 7.2 OpenAI 兼容端点\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='Your LLM Model name',\n llm_base_url='Your LLM Model url',\n embedding_model_name='Your Embedding model name',\n embedding_base_url='Your Embedding model url'\n)\n```\n\n### 7.3 main.py 核心逻辑\n\n```python\ndef main():\n args = parse_args()\n \n # 加载数据集\n corpus, all_queries, gold_docs, gold_answers = load_data(args.dataset)\n \n # 配置参数\n config = BaseConfig(\n dataset=args.dataset,\n openie_mode=args.openie_mode,\n information_extraction_model_name=args.llm_name,\n retrieval_top_k=200,\n linking_top_k=5,\n max_qa_steps=3,\n qa_top_k=5,\n graph_type=\"facts_and_sim_passage_node_unidirectional\",\n embedding_batch_size=8,\n corpus_len=len(corpus)\n )\n \n # 初始化并运行\n hipporag = HippoRAG(global_config=config)\n hipporag.index(corpus)\n hipporag.rag_qa(\n queries=all_queries,\n gold_docs=gold_docs,\n gold_answers=gold_answers\n )\n```\n\n资料来源：[main.py:1]()\n\n## 8. 常见问题排查\n\n### 8.1 GPU 显存不足 (OOM)\n\n**解决方案：**\n\n1. 减小 `gpu-memory-utilization` 参数（建议从 0.95 逐步降低）\n2. 减小 `max_model_len` 参数\n3. 增加 `tensor-parallel-size` 以分散显存占用\n\n### 8.2 OpenAI API 调用失败\n\n**检查项：**\n\n1. 确认 `OPENAI_API_KEY` 环境变量已正确设置\n2. 验证 API 端点 URL 格式正确\n3. 检查网络连接和代理设置\n\n### 8.3 vLLM 服务无响应\n\n**排查步骤：**\n\n1. 确认 vLLM 服务进程正在运行\n2. 检查端口 6578 是否被占用\n3. 验证 GPU 可见性配置正确\n\n## 9. 参考链接\n\n| 资源 | 链接 |\n|------|------|\n| HippoRAG 2 论文 | [arXiv:2502.14802](https://arxiv.org/abs/2502.14802) |\n| HippoRAG 1 论文 | [arXiv:2405.14831](https://arxiv.org/abs/2405.14831) |\n| HuggingFace 数据集 | [osunlp/HippoRAG_v2](https://huggingface.co/datasets/osunlp/HippoRAG_v2) |\n| vLLM 文档 | [docs.vllm.ai](https://docs.vllm.ai/en/latest/getting_started/quickstart.html) |\n| GitHub 仓库 | [OSU-NLP-Group/HippoRAG](https://github.com/OSU-NLP-Group/HippoRAG) |\n\n---\n\n\n\n## 评估与测试\n\n### 相关页面\n\n相关主题：[实验复现指南](#p9), [Prompt模板管理](#p8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/evaluation/qa_eval.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/qa_eval.py)\n- [src/hipporag/evaluation/retrieval_eval.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/retrieval_eval.py)\n- [src/hipporag/evaluation/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/base.py)\n- [tests_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)\n- [tests_local.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_local.py)\n- [tests_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_azure.py)\n \n\n# 评估与测试\n\n## 概述\n\nHippoRAG 提供了完整的评估与测试框架，用于验证系统的索引构建、检索质量和问答能力。评估模块位于 `src/hipporag/evaluation/` 目录下，分为问答评估（QA Evaluation）和检索评估（Retrieval Evaluation）两个核心组件。资料来源：[README.md:代码结构]()\n\n该框架支持多种部署方式的测试，包括 OpenAI API、Azure OpenAI Service 和本地 vLLM 部署。通过统一的测试接口，开发者可以验证核心模块的功能完整性，包括索引构建、图加载、文档删除和增量更新等关键能力。\n\n---\n\n## 评估模块架构\n\n### 模块结构\n\nHippoRAG 的评估系统采用分层设计，包含基础评估类和具体评估实现。\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| 基础评估类 | `src/hipporag/evaluation/base.py` | 定义 `BaseMetric` 基类，供所有评估指标继承 |\n| 问答评估 | `src/hipporag/evaluation/qa_eval.py` | 实现问答任务的评估指标 |\n| 检索评估 | `src/hipporag/evaluation/retrieval_eval.py` | 实现检索任务的评估指标 |\n\n资料来源：[README.md:代码结构]()\n\n### 评估流程\n\n```mermaid\ngraph TD\n A[输入查询] --> B[检索阶段]\n B --> C[文档排序]\n C --> D[Top-K 文档]\n D --> E[QA 模型回答]\n E --> F[评估结果]\n \n G[黄金标准] --> F\n D --> G\n E --> G\n```\n\n评估系统通过对比系统输出与黄金标准（gold standard）来计算性能指标。在 `rag_qa` 方法中，系统接收查询、黄金文档和黄金答案，并返回包含评估指标的完整结果。资料来源：[tests_openai.py:测试流程]()\n\n---\n\n## 核心评估指标\n\n### 问答评估（QA Evaluation）\n\n问答评估模块负责衡量 HippoRAG 生成答案的质量。评估过程接收以下输入参数：\n\n| 参数名 | 类型 | 描述 |\n|--------|------|------|\n| queries | List[str] | 查询问题列表 |\n| gold_docs | List[List[str]] | 每个查询对应的黄金文档 |\n| gold_answers | List[List[str]] | 每个查询对应的黄金答案 |\n\n资料来源：[tests_openai.py:评估参数]()\n\n```python\n# 典型评估调用示例\nanswers = [\n [\"Politician\"], # 黄金答案\n [\"By going to the ball.\"],\n [\"Rockland County\"]\n]\n\ngold_docs = [\n [\"George Rankin is a politician.\"],\n [\"Cinderella attended the royal ball.\",\n \"The prince used the lost glass slipper...\"],\n [\"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"]\n]\n\nresult = hipporag.rag_qa(queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers)\n```\n\n### 检索评估（Retrieval Evaluation）\n\n检索评估模块衡量文档检索的准确性和相关性。该模块评估系统是否能正确识别与查询相关的文档，支持多跳推理场景下的关联检索评估。\n\n---\n\n## 测试框架\n\n### 测试类型概览\n\nHippoRAG 提供了三种测试方式以适应不同的部署环境：\n\n| 测试类型 | 测试文件 | 适用场景 |\n|----------|----------|----------|\n| OpenAI 测试 | `tests_openai.py` | 使用 OpenAI API 进行测试 |\n| 本地测试 | `tests_local.py` | 使用本地 vLLM 部署进行测试 |\n| Azure 测试 | `tests_azure.py` | 使用 Azure OpenAI Service 进行测试 |\n\n资料来源：[README.md:Testing](), [tests_openai.py](), [tests_local.py]()\n\n### 测试环境配置\n\n#### OpenAI 测试\n\nOpenAI 测试是最简单的方式，无需本地部署 LLM。只需配置 API 密钥即可运行：\n\n```bash\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n资料来源：[README.md:OpenAI Test]()\n\n#### 本地测试（vLLM）\n\n本地测试需要先部署 vLLM 服务器，然后运行测试脚本：\n\n```bash\n# 步骤 1：部署 vLLM 服务器\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n --tensor-parallel-size 2 \\\n --max_model_len 4096 \\\n --gpu-memory-utilization 0.95 \\\n --port 6578\n\n# 步骤 2：运行测试\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:Local Test]()\n\n#### Azure 测试\n\nAzure 测试使用 Azure OpenAI Service 的部署端点进行测试，配置方式如下：\n\n```python\nhipporag = HippoRAG(save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name,\n azure_endpoint=\"https://[ENDPOINT].openai.azure.com/...\",\n azure_embedding_endpoint=\"https://[ENDPOINT].openai.azure.com/...\")\n```\n\n### 测试覆盖范围\n\nHippoRAG 的测试套件覆盖以下核心功能：\n\n| 测试场景 | 描述 |\n|----------|------|\n| 索引构建 | 验证文档索引的完整性和正确性 |\n| 图加载 | 验证知识图谱的加载和解析 |\n| 文档删除 | 验证从索引中删除文档的功能 |\n| 增量更新 | 验证向现有索引添加新文档的能力 |\n\n资料来源：[README.md:Testing]()\n\n### 测试执行流程\n\n```mermaid\ngraph LR\n A[准备测试数据] --> B[初始化 HippoRAG]\n B --> C[执行索引构建]\n C --> D[运行 RAG QA]\n D --> E[验证评估结果]\n E --> F{测试通过?}\n F -->|是| G[输出结果]\n F -->|否| H[报告错误]\n```\n\n---\n\n## HippoRAG 类测试方法\n\n### 主要测试方法\n\nHippoRAG 类提供了 `rag_qa` 方法用于执行检索增强问答并返回评估结果：\n\n```python\ndef rag_qa(queries: List[str],\n gold_docs: List[List[str]],\n gold_answers: List[List[str]]) -> Any\n```\n\n返回值包含评估指标和系统输出，可通过切片 `[-2:]` 获取最终的评估结果。\n\n资料来源：[tests_openai.py:rag_qa调用](), [tests_local.py:rag_qa调用]()\n\n### 端到端测试示例\n\n以下是一个完整的端到端测试流程：\n\n```python\nfrom hipporag import HippoRAG\n\n# 初始化配置\nsave_dir = 'outputs'\nllm_model_name = 'gpt-4o-mini'\nembedding_model_name = 'nvidia/NV-Embed-v2'\n\n# 创建实例\nhipporag = HippoRAG(save_dir=save_dir,\n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name)\n\n# 测试数据\ndocs = [\n \"George Rankin is a politician.\",\n \"Cinderella attended the royal ball.\",\n \"Erik Hort's birthplace is Montebello.\",\n \"Montebello is a part of Rockland County.\"\n]\n\n# 执行索引\nhipporag.index(docs=docs)\n\n# 执行评估\nqueries = [\"What is George Rankin's occupation?\"]\nanswers = [[\"Politician\"]]\ngold_docs = [[\"George Rankin is a politician.\"]]\n\nresult = hipporag.rag_qa(queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers)\n\nprint(result[-2:])\n```\n\n---\n\n## 配置参数\n\n### 全局配置（BaseConfig）\n\n评估相关的配置参数位于 `BaseConfig` 类中：\n\n| 参数名 | 默认值 | 描述 |\n|--------|--------|------|\n| retrieval_top_k | 200 | 每步检索的文档数量 |\n| linking_top_k | 5 | 每个检索步骤的链接节点数 |\n| max_qa_steps | 3 | 问答最大迭代步数 |\n| qa_top_k | 5 | 输入 QA 模型的顶部文档数 |\n| damping | 0.5 | PPR 算法的阻尼因子 |\n| graph_type | facts_and_sim_passage_node_unidirectional | 图结构类型 |\n\n资料来源：[src/hipporag/utils/config_utils.py:配置参数]()\n\n---\n\n## 最佳实践\n\n### 测试建议\n\n1. **环境验证**：首次使用前，使用 `sample` 数据集进行环境验证\n2. **成本控制**：开发测试优先使用 OpenAI 测试，成本最低\n3. **模型选择**：本地测试推荐使用较小的 8B 模型（如 Llama-3.1-8B-Instruct）以节省 GPU 内存\n4. **资源调优**：如遇 GPU 内存溢出，可调整 `gpu-memory-utilization` 或 `max_model_len` 参数\n\n### 调试建议\n\n测试失败时，按以下顺序排查：\n\n1. 确认 API 密钥或本地服务是否正常\n2. 检查数据集格式是否符合规范（JSON 结构）\n3. 验证环境变量配置是否正确\n4. 检查 GPU 内存是否充足\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：OSU-NLP-Group/HippoRAG\n\n摘要：发现 18 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：add_fact_edges function adds the same edge twice?。\n\n## 1. 安装坑 · 来源证据：add_fact_edges function adds the same edge twice?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：add_fact_edges function adds the same edge twice?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6c7ca8232561460290f1ad50663233af | https://github.com/OSU-NLP-Group/HippoRAG/issues/174 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：pypi hipporag libraries\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：pypi hipporag libraries\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0da5afa434114138a3c745efba4c9ded | https://github.com/OSU-NLP-Group/HippoRAG/issues/168 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an extremely long time. Is this normal?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_90b68b1be49048efba510bfd10623d41 | https://github.com/OSU-NLP-Group/HippoRAG/issues/173 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：OpenAI version incompatibility in latest 2.0.0a4 version\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OpenAI version incompatibility in latest 2.0.0a4 version\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f6679eb5cf884eb9a2d003b39da93c8d | https://github.com/OSU-NLP-Group/HippoRAG/issues/140 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Windows Compatibility Issues with vLLM dependency\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows Compatibility Issues with vLLM dependency\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57d57b9365f342db9a5e8ed48727e99e | https://github.com/OSU-NLP-Group/HippoRAG/issues/117 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：How to use local embedding_model_\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：How to use local embedding_model_\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dd0e2350e55240b3ab754359ca93cb11 | https://github.com/OSU-NLP-Group/HippoRAG/issues/127 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b735fa4a09f942db8f1825092ef8e368 | https://github.com/OSU-NLP-Group/HippoRAG/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：How to distinguish Hipporag1 from Hipporag2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to distinguish Hipporag1 from Hipporag2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7dc27422dd8b4cb8a1384848ddbfa750 | https://github.com/OSU-NLP-Group/HippoRAG/issues/167 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Inquiry on Sample Selection for HippoRAG Experiments\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Inquiry on Sample Selection for HippoRAG Experiments\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6a0069bfedfc4cf28e0cc18e51171a42 | https://github.com/OSU-NLP-Group/HippoRAG/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Quadratic runtime during indexing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Quadratic runtime during indexing\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2681acee71064f72b24098fba0e05227 | https://github.com/OSU-NLP-Group/HippoRAG/issues/170 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b65aca3d12234444b97a67bb7baac278 | https://github.com/OSU-NLP-Group/HippoRAG/issues/178 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：division by zero\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：division by zero\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49e401ba15b74b5d943336fa0a2dceda | https://github.com/OSU-NLP-Group/HippoRAG/issues/93 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：OSU-NLP-Group/HippoRAG\n\n摘要：发现 18 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：add_fact_edges function adds the same edge twice?。\n\n## 1. 安装坑 · 来源证据：add_fact_edges function adds the same edge twice?\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：add_fact_edges function adds the same edge twice?\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6c7ca8232561460290f1ad50663233af | https://github.com/OSU-NLP-Group/HippoRAG/issues/174 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：pypi hipporag libraries\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：pypi hipporag libraries\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0da5afa434114138a3c745efba4c9ded | https://github.com/OSU-NLP-Group/HippoRAG/issues/168 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an…\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Take the \"musique\" dataset as an example. The process of constructing an index based on individual paragraphs takes an extremely long time. Is this normal?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_90b68b1be49048efba510bfd10623d41 | https://github.com/OSU-NLP-Group/HippoRAG/issues/173 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：OpenAI version incompatibility in latest 2.0.0a4 version\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：OpenAI version incompatibility in latest 2.0.0a4 version\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f6679eb5cf884eb9a2d003b39da93c8d | https://github.com/OSU-NLP-Group/HippoRAG/issues/140 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Windows Compatibility Issues with vLLM dependency\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Windows Compatibility Issues with vLLM dependency\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_57d57b9365f342db9a5e8ed48727e99e | https://github.com/OSU-NLP-Group/HippoRAG/issues/117 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 配置坑 · 来源证据：How to use local embedding_model_\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：How to use local embedding_model_\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dd0e2350e55240b3ab754359ca93cb11 | https://github.com/OSU-NLP-Group/HippoRAG/issues/127 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Inquiry Regarding OpenIE Extraction Results for HippoRAG 2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b735fa4a09f942db8f1825092ef8e368 | https://github.com/OSU-NLP-Group/HippoRAG/issues/177 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | last_activity_observed missing\n\n## 10. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium\n\n## 11. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | no_demo; severity=medium\n\n## 12. 安全/权限坑 · 来源证据：How to distinguish Hipporag1 from Hipporag2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：How to distinguish Hipporag1 from Hipporag2\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7dc27422dd8b4cb8a1384848ddbfa750 | https://github.com/OSU-NLP-Group/HippoRAG/issues/167 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 13. 安全/权限坑 · 来源证据：Inquiry on Sample Selection for HippoRAG Experiments\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Inquiry on Sample Selection for HippoRAG Experiments\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6a0069bfedfc4cf28e0cc18e51171a42 | https://github.com/OSU-NLP-Group/HippoRAG/issues/125 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 安全/权限坑 · 来源证据：Quadratic runtime during indexing\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Quadratic runtime during indexing\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2681acee71064f72b24098fba0e05227 | https://github.com/OSU-NLP-Group/HippoRAG/issues/170 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 15. 安全/权限坑 · 来源证据：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Discussion] Ablation: multi-component scoring layer over HippoRAG's KG?\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_b65aca3d12234444b97a67bb7baac278 | https://github.com/OSU-NLP-Group/HippoRAG/issues/178 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：division by zero\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：division by zero\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_49e401ba15b74b5d943336fa0a2dceda | https://github.com/OSU-NLP-Group/HippoRAG/issues/93 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | issue_or_pr_quality=unknown\n\n## 18. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:805115184 | https://github.com/OSU-NLP-Group/HippoRAG | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# HippoRAG - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 HippoRAG 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: HippoRAG 2: From RAG to Memory
输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. p1：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. p2：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. p3：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. p4：知识图谱构建。围绕“知识图谱构建”模拟一次用户任务，不展示安装或运行结果。\n5. p5：LLM模型集成。围绕“LLM模型集成”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. p1\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. p2\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. p3\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. p4\n输入：用户提供的“知识图谱构建”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. p5\n输入：用户提供的“LLM模型集成”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / p1：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / p2：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / p3：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / p4：Step 4 必须围绕“知识图谱构建”形成一个小中间产物，并等待用户确认。\n- Step 5 / p5：Step 5 必须围绕“LLM模型集成”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/OSU-NLP-Group/HippoRAG\n- https://github.com/OSU-NLP-Group/HippoRAG#readme\n- README.md\n- src/hipporag/HippoRAG.py\n- requirements.txt\n- demo_openai.py\n- demo_local.py\n- src/hipporag/StandardRAG.py\n- src/hipporag/embedding_store.py\n- src/hipporag/utils/config_utils.py\n- src/hipporag/llm/base.py\n- src/hipporag/llm/openai_gpt.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 HippoRAG 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：OSU-NLP-Group/HippoRAG\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install hipporag\n```\n\n来源：https://github.com/OSU-NLP-Group/HippoRAG#readme\n\n## 来源\n\n- repo: https://github.com/OSU-NLP-Group/HippoRAG\n- docs: https://github.com/OSU-NLP-Group/HippoRAG#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_b637e1ee2e31488884f3c56dfa70fcd5"
}