{
"canonical_name": "OSU-NLP-Group/HippoRAG",
"compilation_id": "pack_77bcc21325444eadabd209e1bbb70f00",
"created_at": "2026-05-16T23:44:02.656904+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": "Workflow Automation",
"label_zh": "流程自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-workflow-automation",
"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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for OSU-NLP-Group/HippoRAG.\n\nProject:\n- Name: HippoRAG\n- Repository: https://github.com/OSU-NLP-Group/HippoRAG\n- Summary: HippoRAG 2: From RAG to Memory
\n- Host target: chatgpt\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: HippoRAG 2: From RAG to Memory
\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: HippoRAG 2: From RAG to Memory
\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-1: Installation and Setup. Produce one small intermediate artifact and wait for confirmation.\n2. page-2: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-4: HippoRAG Core Class. Produce one small intermediate artifact and wait for confirmation.\n4. page-5: Knowledge Graph and Retrieval. Produce one small intermediate artifact and wait for confirmation.\n5. page-7: LLM Integrations. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/OSU-NLP-Group/HippoRAG\n- https://github.com/OSU-NLP-Group/HippoRAG#readme\n- requirements.txt\n- setup.py\n- README.md\n- demo.py\n- demo_openai.py\n- src/hipporag/HippoRAG.py\n- src/hipporag/StandardRAG.py\n- src/hipporag/utils/embed_utils.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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:41:44 UTC\n\n## 目录\n\n- [Installation and Setup](#page-1)\n- [Quick Start Guide](#page-2)\n- [Configuration System](#page-3)\n- [HippoRAG Core Class](#page-4)\n- [Knowledge Graph and Retrieval](#page-5)\n- [Embedding Store and Management](#page-6)\n- [LLM Integrations](#page-7)\n- [Embedding Models](#page-8)\n- [Open Information Extraction (OpenIE)](#page-9)\n- [Deployment Options](#page-10)\n\n\n\n## Installation and Setup\n\n### 相关页面\n\n相关主题：[Configuration System](#page-3), [Deployment Options](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [test_transformers.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/test_transformers.py)\n- [CONTRIBUTING.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/CONTRIBUTING.md)\n \n\n# Installation and Setup\n\n## Overview\n\nHippoRAG is a graph-based Retrieval-Augmented Generation (RAG) framework designed to enable Large Language Models (LLMs) to identify and leverage connections within knowledge bases for improved retrieval and question answering. The installation process configures the necessary dependencies, environment variables, and model configurations to run HippoRAG in either cloud (OpenAI) or local (vLLM) deployment modes.\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## System Requirements\n\n### Python Version\n\n| Requirement | Version |\n|-------------|---------|\n| Python | >= 3.10 |\n\nThe package explicitly requires Python 3.10 or higher as specified in the `setup.py` configuration.\n\n资料来源：[setup.py:16](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L16)\n\n### Hardware Requirements\n\n| Component | Requirement |\n|-----------|-------------|\n| GPU | CUDA-compatible GPU(s) recommended |\n| GPU Memory | Varies based on model size (see deployment sections) |\n\nFor local deployment with vLLM, the framework supports tensor parallelism across multiple GPUs. The README recommends reserving enough memory for embedding models when deploying LLM servers.\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Installation Methods\n\n### Method 1: pip Installation (Recommended)\n\n```sh\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install hipporag\n```\n\nThis method installs HippoRAG version 2.0.0-alpha.4 along with all core dependencies from PyPI.\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Method 2: Source Installation (For Development)\n\n```sh\ngit clone https://github.com/OSU-NLP-Group/HippoRAG.git\ncd HippoRAG\npip install -e .\n```\n\nClone the repository and install in editable mode to work with the latest source code.\n\n资料来源：[CONTRIBUTING.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/CONTRIBUTING.md)\n\n## Environment Variables\n\nProper configuration of environment variables is essential for HippoRAG to function correctly. These variables control GPU allocation, model caching, and API access.\n\n### Required Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `CUDA_VISIBLE_DEVICES` | Comma-separated list of GPU device IDs | `0,1,2,3` |\n| `HF_HOME` | Path to Hugging Face cache directory | `/path/to/huggingface/home` |\n| `OPENAI_API_KEY` | API key for OpenAI models (cloud mode only) | `sk-...` |\n\n### Setting Environment Variables\n\n```sh\n# Set CUDA visible devices\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\n\n# Set Hugging Face cache location\nexport HF_HOME=\n\n# Set OpenAI API key (required for cloud deployment)\nexport OPENAI_API_KEY=\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Core Dependencies\n\nHippoRAG depends on a comprehensive set of libraries for LLM inference, embedding models, graph processing, and data handling.\n\n### Dependency Overview\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| torch | 2.5.1 | PyTorch deep learning framework |\n| transformers | 4.45.2 | Model architectures and tokenizers |\n| vllm | 0.6.6.post1 | High-throughput LLM inference |\n| openai | 1.91.1 | OpenAI API client |\n| litellm | 1.73.1 | Unified LLM interface |\n| gritlm | 1.0.2 | Embedding model |\n| networkx | 3.4.2 | Graph data structures |\n| python_igraph | 0.11.8 | Graph algorithms |\n| tiktoken | 0.7.0 | Tokenization |\n| pydantic | 2.10.4 | Data validation |\n| tenacity | 8.5.0 | Retry logic |\n| einops | (latest) | Tensor operations |\n| tqdm | (latest) | Progress bars |\n| boto3 | (latest) | AWS S3 integration |\n\n资料来源：[setup.py:17-32](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L17-L32), [requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n\n### Additional Dependencies\n\nThe `requirements.txt` file includes additional packages not pinned to specific versions:\n\n| Package | Purpose |\n|---------|---------|\n| nest_asyncio | Asynchronous operations |\n| numpy | Numerical computing |\n| scipy | Scientific computing |\n\n资料来源：[requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n\n## Configuration\n\nHippoRAG uses a Pydantic-based configuration system defined in `BaseConfig` within `config_utils.py`. This configuration controls all aspects of indexing, retrieval, and QA.\n\n### Configuration Parameters\n\n#### Embedding Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| embedding_model_name | nvidia/NV-Embed-v2 | Name of the embedding model |\n| embedding_batch_size | 16 | Batch size for embedding encoding |\n| embedding_return_as_normalized | True | Whether to normalize embeddings |\n| embedding_max_seq_len | 2048 | Maximum sequence length for embeddings |\n| embedding_model_dtype | auto | Data type for local embedding models |\n\n#### Retrieval Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| retrieval_top_k | 200 | Number of documents to retrieve |\n| linking_top_k | 5 | Number of linked nodes per retrieval step |\n| damping | 0.5 | Damping factor for PPR algorithm |\n| passage_node_weight | 0.05 | Weight modifier for passage nodes in PPR |\n\n#### QA Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| max_qa_steps | 1 | Maximum steps for interleaved retrieval and reasoning |\n| qa_top_k | 5 | Top k documents fed to QA model |\n\n#### Graph Construction Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| synonymy_edge_topk | 2047 | K for KNN retrieval in synonymy edge building |\n| synonymy_edge_sim_threshold | 0.8 | Similarity threshold for synonymy nodes |\n| is_directed_graph | False | Whether the graph is directed |\n| graph_type | facts_and_sim_passage_node_unidirectional | Type of graph structure |\n\n#### Information Extraction Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| information_extraction_model_name | openie_openai_gpt | OpenIE model class name |\n| openie_mode | online | Mode: \"online\" or \"offline\" |\n\n#### Preprocessing Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| text_preprocessor_class_name | TextPreprocessor | Preprocessor class name |\n| preprocess_encoder_name | gpt-4o | Encoder for preprocessing |\n| preprocess_chunk_overlap_token_size | 128 | Overlap tokens between chunks |\n| preprocess_chunk_max_token_size | None | Max tokens per chunk (None = whole doc) |\n| preprocess_chunk_func | by_token | Chunking function type |\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## Deployment Modes\n\nHippoRAG supports two primary deployment modes for LLM inference.\n\n```mermaid\ngraph TD\n A[HippoRAG Deployment] --> B[Cloud Mode]\n A --> C[Local Mode]\n \n B --> B1[OpenAI API]\n B --> B2[OpenAI Compatible API]\n \n C --> C1[vLLM Server]\n C --> C1b[Local Embedding Model]\n \n B1 --> D[Requires OPENAI_API_KEY]\n B2 --> E[Custom LLM Base URL]\n C1 --> F[Multi-GPU Support]\n```\n\n### Cloud Mode (OpenAI)\n\nCloud mode uses OpenAI's API for both LLM and embedding inference.\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\n#### OpenAI Compatible Embeddings\n\nFor OpenAI-compatible embedding endpoints:\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资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Local Mode (vLLM)\n\nLocal mode deploys LLM servers using vLLM for offline inference with GPU acceleration.\n\n#### Step 1: Start vLLM Server\n\n```sh\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#### Step 2: Run HippoRAG with Different GPUs\n\n```sh\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\npython main.py --dataset sample --llm_base_url http://localhost:6578/v1\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Quick Start Workflow\n\n```mermaid\ngraph LR\n A[Install HippoRAG] --> B[Configure Environment]\n B --> C[Set Environment Variables]\n C --> D[Initialize HippoRAG]\n D --> E[index Documents]\n E --> F[RAG QA Queries]\n```\n\n### Complete Example\n\n```python\nfrom hipporag import HippoRAG\n\n# Define documents\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# Initialize 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# Index documents\nhipporag.index(docs)\n\n# Define queries and gold standard answers\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\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 [\"Montebello is a part of Rockland County.\"]\n]\n\nanswers = [\n [\"Politician\"],\n [\"By going to the ball.\"],\n [\"Rockland County\"]\n]\n\n# Run RAG QA\nresults = 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## Testing Your Installation\n\n### OpenAI Test\n\nRun this test to verify cloud mode functionality:\n\n```sh\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n### Local Test\n\nRun this test to verify local vLLM mode:\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\n# Start vLLM server\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# Run local test\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Troubleshooting\n\n### Out of Memory (OOM) Errors\n\nIf you encounter OOM errors during local deployment:\n\n1. Reduce `gpu-memory-utilization` parameter in vLLM\n2. Reduce `max_model_len` in vLLM server\n3. Adjust `CUDA_VISIBLE_DEVICES` to use more GPUs\n4. Reduce `embedding_batch_size` in configuration\n\n### Environment Variable Issues\n\nEnsure all required environment variables are set before running HippoRAG:\n\n```sh\n# Verify environment variables are set\necho $CUDA_VISIBLE_DEVICES\necho $HF_HOME\necho $OPENAI_API_KEY\n```\n\n### Conda Environment\n\nAlways activate the correct conda environment before running commands:\n\n```sh\nconda activate hipporag\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Reproducing Experiments\n\nTo reproduce the paper's experiments:\n\n1. Clone the repository and install dependencies\n2. Download datasets from [HuggingFace](https://huggingface.co/datasets/osunlp/HippoRAG_v2) or use provided samples in `reproduce/dataset`\n3. Set required environment variables\n4. Run the main script with appropriate parameters:\n\n```sh\n# OpenAI model\npython main.py \\\n --dataset sample \\\n --llm_base_url https://api.openai.com/v1 \\\n --llm_name gpt-4o-mini \\\n --embedding_name nvidia/NV-Embed-v2\n\n# Local vLLM model\npython main.py \\\n --dataset sample \\\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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md), [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Installation and Setup](#page-1), [HippoRAG Core Class](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [demo_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.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- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)\n- [requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n \n\n# Quick Start Guide\n\nThis guide provides a comprehensive walkthrough for setting up and running HippoRAG, enabling you to quickly leverage neurobiologically inspired long-term memory capabilities for Large Language Models.\n\n## Prerequisites\n\nBefore beginning, ensure your environment meets the following requirements:\n\n| Requirement | Specification |\n|------------|---------------|\n| Python | >= 3.10 |\n| CUDA GPUs | Required for local embedding model inference |\n| HuggingFace Home | Configured via `HF_HOME` environment variable |\n| API Keys | OpenAI API key (if using OpenAI models) |\n\n### Environment Setup\n\n```sh\n# Create conda environment\nconda create -n hipporag python=3.10\nconda activate hipporag\n\n# Install HippoRAG\npip install hipporag\n\n# Configure environment variables\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=\n```\n\n资料来源：[README.md:150-165]()\n\n## Core Usage Patterns\n\nHippoRAG supports three primary deployment configurations. The initialization workflow follows this pattern:\n\n```mermaid\ngraph TD\n A[Initialize HippoRAG] --> B{Select LLM Backend}\n B -->|OpenAI| C[Set llm_model_name + llm_base_url]\n B -->|vLLM| D[Set llm_model_name + llm_base_url]\n B -->|Azure| E[Set azure_endpoint]\n A --> F{Select Embedding Backend}\n F -->|HuggingFace| G[Set embedding_model_name]\n F -->|Custom| H[Set embedding_base_url]\n```\n\n资料来源：[demo_azure.py:1-30]()\n\n### Pattern 1: OpenAI Models\n\nThe simplest configuration uses OpenAI for both LLM inference and embeddings:\n\n```python\nfrom hipporag import HippoRAG\n\n# Configuration\nsave_dir = 'outputs'\nllm_model_name = 'gpt-4o-mini'\nembedding_model_name = 'nvidia/NV-Embed-v2'\n\n# Initialize HippoRAG instance\nhipporag = HippoRAG(\n save_dir=save_dir, \n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name\n)\n```\n\n资料来源：[README.md:175-195]()\n\n### Pattern 2: OpenAI Compatible Embeddings\n\nFor custom LLM endpoints that follow OpenAI's API format:\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资料来源：[README.md:210-220]()\n\n### Pattern 3: Azure OpenAI Integration\n\nFor Azure-hosted models:\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资料来源：[demo_azure.py:10-15]()\n\n## Indexing Documents\n\nThe indexing process converts raw documents into HippoRAG's knowledge graph structure:\n\n```mermaid\ngraph LR\n A[Raw Documents] --> B[Chunking]\n B --> C[OpenIE Extraction]\n C --> D[Embedding Generation]\n D --> E[Graph Construction]\n E --> F[Knowledge Graph Index]\n```\n\n### Input Data Format\n\nDocuments should be provided as a list of strings:\n\n```python\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]\n```\n\n### Execute Indexing\n\n```python\nhipporag.index(docs=docs)\n```\n\n资料来源：[demo_azure.py:18-45]()\n\n## Retrieval and Question Answering\n\nThe `rag_qa` method performs retrieval-augmented question answering:\n\n```mermaid\ngraph TD\n A[Query Input] --> B[Retrieval]\n B --> C[Personalized PageRank]\n C --> D[Document Selection]\n D --> E[QA Generation]\n E --> F[Final Answer]\n \n C -.->|links documents| G[Knowledge Graph]\n G -.->|context| D\n```\n\n### Complete QA Example\n\n```python\n# Prepare queries and evaluation data\nqueries = [\n \"What is George Rankin's occupation?\",\n \"How did Cinderella reach her happy ending?\"\n]\n\nanswers = [\n [\"Politician\"],\n [\"By going to the ball.\"]\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]\n\n# Execute RAG QA\nresults = hipporag.rag_qa(\n queries=queries, \n gold_docs=gold_docs,\n gold_answers=answers\n)\n\nprint(results)\n```\n\n资料来源：[README.md:195-215]()\n\n## Local Deployment with vLLM\n\nFor running LLMs locally, HippoRAG supports vLLM server integration:\n\n### Step 1: Start vLLM Server\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nconda activate hipporag\n\n# Adjust gpu-memory-utilization and max_model_len based on your GPU memory\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:225-240]()\n\n### Step 2: Initialize HippoRAG with vLLM\n\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 embedding_model_name='nvidia/NV-Embed-v2'\n)\n```\n\n## Reproducing Experiments\n\nFor reproducing published experiments, follow the structured workflow:\n\n### Dataset Structure\n\n| File Type | Naming Convention | Purpose |\n|-----------|-------------------|---------|\n| Corpus | `{dataset}_corpus.json` | Document collection |\n| Queries | `{dataset}.json` | Questions with answers |\n| Output | `outputs/{dataset}/` | Index and results |\n\n### Corpus JSON Format\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:100-125]()\n\n### Running Experiments\n\n```sh\n# Set environment variables\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=\nconda activate hipporag\n\n# Run with OpenAI model\ndataset=sample\npython main.py --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资料来源：[main.py:1-35]()\n\n## Testing Your Installation\n\n### OpenAI Test\n\nVerify installation with minimal OpenAI API cost:\n\n```sh\nexport OPENAI_API_KEY= \nconda activate hipporag\npython tests_openai.py\n```\n\n### Local Test with vLLM\n\nTest with a locally deployed model:\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nconda activate hipporag\n\n# Start vLLM server with smaller model\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# Run test\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:250-280]()\n\n## Configuration Parameters\n\n### Core Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `save_dir` | `outputs` | Directory for saving all related information |\n| `llm_model_name` | - | LLM model identifier |\n| `llm_base_url` | - | Base URL for LLM API endpoint |\n| `embedding_model_name` | `nvidia/NV-Embed-v2` | Embedding model identifier |\n| `embedding_batch_size` | `16` | Batch size for embedding model |\n\n资料来源：[src/hipporag/utils/config_utils.py:50-80]()\n\n### Retrieval Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `retrieval_top_k` | `200` | Number of documents to retrieve initially |\n| `linking_top_k` | `5` | Number of linked nodes at each retrieval step |\n| `qa_top_k` | `5` | Number of documents fed to QA model |\n| `max_qa_steps` | `1` | Maximum interleaved retrieval-reasoning steps |\n| `damping` | `0.5` | Damping factor for Personalized PageRank |\n\n资料来源：[src/hipporag/utils/config_utils.py:30-50]()\n\n### Graph Construction Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `synonymy_edge_topk` | `2047` | K for KNN retrieval in synonymy edge building |\n| `synonymy_edge_sim_threshold` | `0.8` | Similarity threshold for synonymy nodes |\n| `graph_type` | `facts_and_sim_passage_node_unidirectional` | Type of graph structure to construct |\n| `is_directed_graph` | `False` | Whether to build a directed graph |\n\n资料来源：[src/hipporag/utils/config_utils.py:80-110]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| CUDA OOM errors | Reduce `gpu-memory-utilization` or `max_model_len` in vLLM; reduce `embedding_batch_size` |\n| Connection errors | Verify API endpoint URLs and network connectivity |\n| Index loading failures | Check that `save_dir` contains valid index files |\n\n### Environment Validation\n\nAlways verify your setup before running experiments:\n\n```sh\n# Verify CUDA availability\npython -c \"import torch; print(torch.cuda.is_available())\"\n\n# Verify package installation\npip list | grep hipporag\n```\n\n## Next Steps\n\n- Explore the [Code Structure documentation](README.md#code-structure) for deep-dive into modules\n- Review experiment reproducibility guidelines in `main.py`\n- Access pre-processed datasets from the [HuggingFace dataset page](https://huggingface.co/datasets/osunlp/HippoRAG_v2)\n\n---\n\n\n\n## Configuration System\n\n### 相关页面\n\n相关主题：[Installation and Setup](#page-1), [HippoRAG Core Class](#page-4)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation page:\n\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\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- [tests_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)\n- [test_transformers.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/test_transformers.py)\n \n\n# Configuration System\n\nHippoRAG provides a comprehensive configuration system built on Pydantic's data validation framework. The configuration system enables fine-grained control over all aspects of the indexing, retrieval, and QA pipeline while maintaining type safety and default values for common use cases.\n\n## Architecture Overview\n\nThe configuration system is centered around the `BaseConfig` class defined in `config_utils.py`. This class uses Pydantic's `BaseModel` with `Field` definitions to provide structured configuration with metadata and validation.\n\n```mermaid\ngraph TD\n A[BaseConfig] --> B[OpenIE Configuration]\n A --> C[Embedding Configuration]\n A --> D[Graph Construction Configuration]\n A --> E[Retrieval Configuration]\n A --> F[QA Configuration]\n A --> G[Save/Directory Configuration]\n A --> H[Dataset Configuration]\n \n I[main.py] --> A\n J[HippoRAG class] --> A\n K[StandardRAG class] --> A\n```\n\nSource: [src/hipporag/utils/config_utils.py:1-100]()\n\n## Core Configuration Class\n\n### BaseConfig\n\nThe `BaseConfig` class serves as the single source of truth for all pipeline parameters. It inherits from Pydantic's `BaseModel` and provides automatic validation, serialization, and documentation through field metadata.\n\n```python\nfrom hipporag.utils.config_utils import BaseConfig\n\nglobal_config = BaseConfig(\n openie_mode='openai_gpt',\n information_extraction_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\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)\n```\n\nSource: [main.py:20-35]()\n\n## Configuration Categories\n\n### OpenIE (Open Information Extraction) Configuration\n\nControls the information extraction module that identifies facts and entities from passages.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `openie_mode` | `Literal[\"openai_gpt\", \"vllm_offline\", \"Transformers-offline\"]` | `\"openai_gpt\"` | The mode for information extraction model |\n| `information_extraction_model_name` | `str` | `\"gpt-4o-mini\"` | Model name for information extraction |\n\nThe `openie_mode` parameter supports three execution modes:\n- **`openai_gpt`**: Uses OpenAI's GPT models for extraction via API\n- **`vllm_offline`**: Uses locally deployed LLMs through vLLM server\n- **`Transformers-offline`**: Uses HuggingFace Transformers models directly\n\nSource: [src/hipporag/utils/config_utils.py:config_fields]()\n\n### Embedding Model Configuration\n\nManages embedding generation for passages and queries.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `embedding_model_name` | `str` | `\"nvidia/NV-Embed-v2\"` | Name of the embedding model |\n| `embedding_batch_size` | `int` | `16` | Batch size for embedding generation |\n| `embedding_return_as_normalized` | `bool` | `True` | Whether to normalize embeddings |\n| `embedding_max_seq_len` | `int` | `2048` | Maximum sequence length for embedding model |\n| `embedding_model_dtype` | `Literal[\"float16\", \"float32\", \"bfloat16\", \"auto\"]` | `\"auto\"` | Data type for local embedding model |\n| `embedding_base_url` | `Optional[str]` | `None` | Base URL for OpenAI-compatible embedding endpoints |\n\nSource: [src/hipporag/utils/config_utils.py:embedding_batch_size-def]()\n\n### Graph Construction Configuration\n\nControls the knowledge graph construction process that forms the backbone of HippoRAG's memory system.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `synonymy_edge_topk` | `int` | `2047` | K value for KNN retrieval in building synonymy edges |\n| `synonymy_edge_query_batch_size` | `int` | `1000` | Batch size for query embeddings during KNN retrieval |\n| `synonymy_edge_key_batch_size` | `int` | `10000` | Batch size for key embeddings during KNN retrieval |\n| `synonymy_edge_sim_threshold` | `float` | `0.8` | Similarity threshold for including candidate synonymy nodes |\n| `is_directed_graph` | `bool` | `False` | Whether the constructed graph is directed or undirected |\n| `graph_type` | `str` | `\"facts_and_sim_passage_node_unidirectional\"` | Type of graph structure to build |\n\nSupported `graph_type` values include:\n- `facts_and_sim_passage_node_unidirectional` - Passages connected via facts with similarity edges\n- `facts_and_sim_passage_node_bidirectional` - Bidirectional passage connections\n- `facts_only` - Only fact-based connections\n- `sim_passage_node` - Only passage similarity connections\n\nSource: [src/hipporag/utils/config_utils.py:synonymy_edge_topk-def]()\n\n### Retrieval Configuration\n\nParameters governing the retrieval and linking process using Personalized PageRank (PPR).\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `linking_top_k` | `int` | `5` | Number of linked nodes at each retrieval step |\n| `retrieval_top_k` | `int` | `200` | Number of documents to retrieve at each step |\n| `damping` | `float` | `0.5` | Damping factor for PPR algorithm |\n\nThe `damping` parameter controls the probability of following graph edges during the random walk in PPR. A higher value (closer to 1.0) results in more exploration, while lower values favor exploitation of high-probability paths.\n\nSource: [src/hipporag/utils/config_utils.py:linking_top_k-def](), [main.py:28]()\n\n### QA (Question Answering) Configuration\n\nControls the iterative QA process that interleaves retrieval with reasoning.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `max_qa_steps` | `int` | `1` | Maximum steps for interleaved retrieval and reasoning |\n| `qa_top_k` | `int` | `5` | Number of top documents fed to the QA model |\n\nThe `max_qa_steps` parameter enables multi-step reasoning where the system can retrieve additional documents based on intermediate reasoning results before producing the final answer.\n\nSource: [src/hipporag/utils/config_utils.py:max_qa_steps-def](), [main.py:27]()\n\n### LLM Configuration\n\nManages the language model used for QA and information extraction.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `llm_model_name` | `str` | `\"gpt-4o-mini\"` | Name of the LLM |\n| `llm_base_url` | `Optional[str]` | `None` | Base URL for OpenAI-compatible LLM endpoints |\n| `max_new_tokens` | `Optional[int]` | `None` | Maximum new tokens for generation |\n\nSource: [src/hipporag/utils/config_utils.py:llm_model_name-def]()\n\n### Save and Directory Configuration\n\nControls output persistence and directory structure.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `save_dir` | `str` | `\"outputs\"` | Top-level directory for saving all related information |\n| `corpus_len` | `int` | Required | Length of the corpus being processed |\n\nThe `save_dir` parameter specifies where HippoRAG objects, intermediate results, and evaluation outputs are stored. When running with specific datasets, the default saves to a dataset-customized output directory under `save_dir`.\n\nSource: [src/hipporag/utils/config_utils.py:save_dir-def](), [main.py:32]()\n\n## Configuration Workflow\n\n```mermaid\ngraph LR\n A[Define BaseConfig] --> B[Initialize HippoRAG]\n B --> C[Index Documents]\n C --> D[Run RAG QA]\n D --> E[Results Saved to save_dir]\n \n F[Modify Config] -->|Update| B\n G[New Documents] -->|Index| C\n```\n\n### Initialization Example\n\n```python\nfrom hipporag.utils.config_utils import BaseConfig\nfrom hipporag import HippoRAG\n\nconfig = BaseConfig(\n openie_mode='openai_gpt',\n information_extraction_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\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 max_new_tokens=None,\n corpus_len=len(corpus),\n)\n\nhipporag = HippoRAG(global_config=config)\n```\n\nSource: [main.py:19-38]()\n\n## Configuration for Different Execution Modes\n\n### OpenAI API Mode\n\n```python\nconfig = BaseConfig(\n openie_mode='openai_gpt',\n information_extraction_model_name='gpt-4o-mini',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\n)\n```\n\nSource: [main.py:20-26]()\n\n### Local vLLM Deployment Mode\n\n```python\nconfig = BaseConfig(\n openie_mode='vllm_offline',\n information_extraction_model_name='meta-llama/Llama-3.1-8B-Instruct',\n llm_model_name='meta-llama/Llama-3.3-70B-Instruct',\n llm_base_url='http://localhost:8000/v1',\n embedding_model_name='nvidia/NV-Embed-v2',\n)\n```\n\nSource: [README.md:vllm_example]()\n\n### Transformers Offline Mode\n\n```python\nconfig = BaseConfig(\n openie_mode='Transformers-offline',\n information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\n)\n```\n\nSource: [test_transformers.py:16-20]()\n\n## Testing with Configuration\n\nThe test suite demonstrates configuration usage across different scenarios:\n\n```python\n# tests_openai.py - Basic indexing and QA\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# tests_openai.py - Document deletion\nhipporag.delete(docs_to_delete)\n\n# test_transformers.py - Transformers offline mode\nhipporag = HippoRAG(\n global_config=global_config,\n save_dir=save_dir,\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\n)\n```\n\nSource: [tests_openai.py:test_structure](), [test_transformers.py:16-25]()\n\n## Package Dependencies\n\nThe configuration system depends on the following packages specified in `setup.py`:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `torch` | `2.5.1` | PyTorch backend for models |\n| `transformers` | `4.45.2` | HuggingFace Transformers |\n| `pydantic` | `2.10.4` | Data validation and settings |\n| `vllm` | `0.6.6.post1` | LLM inference server |\n| `openai` | `1.91.1` | OpenAI API client |\n| `litellm` | `1.73.1` | Unified LLM interface |\n| `gritlm` | `1.0.2` | GritLM embedding model |\n| `networkx` | `3.4.2` | Graph operations |\n| `python_igraph` | `0.11.8` | Graph algorithms |\n| `tiktoken` | `0.7.0` | Tokenization |\n| `tenacity` | `8.5.0` | Retry logic |\n\nSource: [setup.py:14-27]()\n\n## Best Practices\n\n1. **Use environment variables** for sensitive configuration like API keys:\n ```bash\n export OPENAI_API_KEY=\n export HF_HOME=\n ```\n\n2. **Set GPU devices** before initialization:\n ```bash\n export CUDA_VISIBLE_DEVICES=0,1,2,3\n ```\n\n3. **Adjust batch sizes** based on available GPU memory when using local models\n\n4. **Configure damping factor** carefully for retrieval - higher values (0.7-0.85) work better for complex multi-hop questions\n\n5. **Set corpus_len** correctly to enable proper progress tracking and memory management\n\n---\n\n\n\n## HippoRAG Core Class\n\n### 相关页面\n\n相关主题：[Knowledge Graph and Retrieval](#page-5), [Embedding Models](#page-8)\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- [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- [main_dpr.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_dpr.py)\n- [tests_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)\n \n\n# HippoRAG Core Class\n\n## Overview\n\nHippoRAG is a neurobiologically inspired graph-based Retrieval-Augmented Generation (RAG) framework designed to enable Large Language Models (LLMs) to identify and leverage connections within knowledge for improved retrieval and question answering. The project implements two primary RAG classes: `HippoRAG` (neurobiologically inspired with Personal Knowledge Graph) and `StandardRAG` (traditional DPR-based approach).\n\n资料来源：[setup.py:8-9]()\n\n## Architecture Overview\n\n```mermaid\ngraph TB\n subgraph \"Input Layer\"\n Docs[Documents/Passages]\n Queries[User Queries]\n end\n \n subgraph \"HippoRAG Core\"\n Index[Indexing Pipeline]\n Retrieve[Retrieval Pipeline]\n QA[Question Answering]\n end\n \n subgraph \"Knowledge Graph Construction\"\n OpenIE[OpenIE Information Extraction]\n Embed[Embedding Model]\n GraphBuild[Graph Building]\n end\n \n subgraph \"Backend Services\"\n LLM[LLM Inference]\n EmbedModel[Embedding Service]\n end\n \n Docs --> Index\n Index --> OpenIE\n Index --> Embed\n OpenIE --> GraphBuild\n Embed --> GraphBuild\n GraphBuild --> KG[Knowledge Graph]\n \n Queries --> Retrieve\n Retrieve --> KG\n KG --> QA\n QA --> LLM\n Retrieve --> EmbedModel\n```\n\n## Core Classes\n\n### HippoRAG Class\n\nThe `HippoRAG` class is the main entry point for the neurobiologically inspired RAG system. It extends a base RAG implementation with Personal Knowledge Graph (PKG) capabilities.\n\n**Initialization Parameters**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `save_dir` | `str` | Required | Directory to save all related information |\n| `llm_model_name` | `str` | Required | LLM model identifier (e.g., `gpt-4o-mini`) |\n| `embedding_model_name` | `str` | Required | Embedding model name (e.g., `nvidia/NV-Embed-v2`) |\n| `global_config` | `BaseConfig` | `None` | Full configuration object |\n| `llm_base_url` | `str` | `None` | Custom LLM API endpoint for OpenAI-compatible models |\n| `embedding_base_url` | `str` | `None` | Custom embedding API endpoint |\n| `azure_endpoint` | `str` | `None` | Azure OpenAI endpoint for LLM |\n| `azure_embedding_endpoint` | `str` | `None` | Azure OpenAI endpoint for embeddings |\n\n资料来源：[main.py:19-28]()\n\n**Basic Usage Pattern**\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# Index documents\nhipporag.index(docs=documents_list)\n\n# Retrieve and answer queries\nresults = hipporag.rag_qa(\n queries=query_list,\n gold_docs=expected_documents,\n gold_answers=expected_answers\n)\n```\n\n### StandardRAG Class\n\nThe `StandardRAG` class provides traditional Dense Passage Retrieval (DPR) based RAG without the Personal Knowledge Graph components. This is useful for baseline comparisons.\n\n资料来源：[main_dpr.py:19]()\n\n## Configuration System\n\n### BaseConfig Parameters\n\nThe `BaseConfig` class (defined in `src/hipporag/utils/config_utils.py`) provides comprehensive configuration options:\n\n**OpenIE Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `openie_mode` | `str` | Required | OpenIE mode: `OpenAI`, `vllm-offline`, or `Transformers-offline` |\n| `information_extraction_model_name` | `str` | `None` | Model for offline OpenIE (e.g., `Qwen/Qwen2.5-7B-Instruct`) |\n\n**Embedding Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `embedding_batch_size` | `int` | `16` | Batch size for embedding model inference |\n| `embedding_return_as_normalized` | `bool` | `True` | Whether to normalize embeddings |\n| `embedding_max_seq_len` | `int` | `2048` | Maximum sequence length for embedding |\n| `embedding_model_dtype` | `str` | `\"auto\"` | Data type: `float16`, `float32`, `bfloat16`, or `auto` |\n\n**Graph Construction Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `synonymy_edge_topk` | `int` | `2047` | K value for KNN retrieval in synonymy edge construction |\n| `synonymy_edge_query_batch_size` | `int` | `1000` | Batch size for query embeddings |\n| `synonymy_edge_key_batch_size` | `int` | `10000` | Batch size for key embeddings |\n| `synonymy_edge_sim_threshold` | `float` | `0.8` | Similarity threshold for synonymy edges |\n| `is_directed_graph` | `bool` | `False` | Whether the graph is directed |\n\n**Retrieval Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `retrieval_top_k` | `int` | `200` | Number of documents to retrieve initially |\n| `linking_top_k` | `int` | `5` | Number of linked nodes at each retrieval step |\n| `damping` | `float` | `0.5` | Damping factor for Personalized PageRank |\n\n**QA Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `max_qa_steps` | `int` | `1` | Maximum interleaved retrieval and reasoning steps |\n| `qa_top_k` | `int` | `5` | Top k documents fed to QA model |\n\n资料来源：[src/hipporag/utils/config_utils.py:1-80]()\n\n## Core Methods\n\n### Indexing Pipeline\n\n```mermaid\ngraph LR\n A[Documents] --> B[Passage Embedding]\n B --> C[OpenIE Extraction]\n C --> D[Fact Node Creation]\n D --> E[Similarity Edge Building]\n E --> F[Knowledge Graph]\n```\n\n**Method Signature**\n\n```python\ndef index(self, docs: List[str], **kwargs) -> None\n```\n\nThe indexing process:\n1. Embeds passages using the configured embedding model\n2. Runs OpenIE to extract factual triples from each passage\n3. Constructs fact nodes and passage nodes in the knowledge graph\n4. Builds synonymy edges based on embedding similarity\n5. Persists the graph structure to `save_dir`\n\n### RAG QA Pipeline\n\n```mermaid\ngraph TD\n Q[Query] --> EP[Embedding]\n EP --> PPR[Personalized PageRank]\n PPR --> LN[Linked Nodes]\n LN --> LLM[LLM Reasoning]\n LLM -->|Iteration| Check{More Steps?}\n Check -->|Yes| EP\n Check -->|No| Final[Final Answer]\n```\n\n**Method Signature**\n\n```python\ndef rag_qa(\n self,\n queries: List[str],\n gold_docs: Optional[List[List[str]]] = None,\n gold_answers: Optional[List[List[str]]] = None,\n **kwargs\n) -> Dict\n```\n\n**Parameters**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `queries` | `List[str]` | Yes | List of questions to answer |\n| `gold_docs` | `List[List[str]]` | No | Ground truth documents for evaluation |\n| `gold_answers` | `List[List[str]]` | No | Ground truth answers for evaluation |\n\n**Returns**\n\nA dictionary containing evaluation metrics and retrieved results.\n\n### Document Deletion\n\n```python\ndef delete(self, docs_to_delete: List[str]) -> None\n```\n\nRemoves specified documents from the knowledge graph and updates persistence.\n\n## Supported Backend Models\n\n### LLM Backends\n\n| Backend | Configuration | Example Model |\n|---------|---------------|---------------|\n| OpenAI | `llm_model_name` | `gpt-4o-mini` |\n| Azure OpenAI | `azure_endpoint` | Azure deployment URL |\n| vLLM (Local) | `llm_base_url` + vLLM server | `meta-llama/Llama-3.1-8B-Instruct` |\n| OpenAI-Compatible | `llm_model_name` + `llm_base_url` | Custom endpoint |\n\n资料来源：[README.md:80-95]()\n\n### Embedding Models\n\n| Model Type | Configuration | Notes |\n|------------|---------------|-------|\n| NV-Embed-v2 | `embedding_model_name='nvidia/NV-Embed-v2'` | Recommended |\n| GritLM | `embedding_model_name='GritLM'` | Supported |\n| Contriever | `embedding_model_name='Contriever'` | Supported |\n| Azure Embeddings | `azure_embedding_endpoint` | Via Azure OpenAI |\n| Custom OpenAI-Compatible | `embedding_base_url` | Any compatible endpoint |\n\n## OpenIE Modes\n\nHippoRAG supports three OpenIE (Open Information Extraction) modes:\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `OpenAI` | Uses OpenAI GPT models for extraction | Cloud-based, high quality |\n| `vllm-offline` | Uses locally deployed vLLM models | GPU-equipped servers |\n| `Transformers-offline` | Uses HuggingFace Transformers | CPU or limited GPU |\n\n资料来源：[test_transformers.py:20-22]()\n\n## Workflow Example\n\n```python\nfrom hipporag import HippoRAG\n\n# Initialize\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# Prepare data\ndocs = [\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Cinderella attended the royal ball.\"\n]\n\n# Index\nhipporag.index(docs=docs)\n\n# Query\nqueries = [\"What is George Rankin's occupation?\"]\nanswers = [[\"Politician\"]]\ngold_docs = [[\"George Rankin is a politician.\"]]\n\n# Retrieve and evaluate\nresults = hipporag.rag_qa(\n queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers\n)\n```\n\n## Graph Types\n\nThe framework supports configurable graph structures:\n\n| Graph Type | Description |\n|------------|-------------|\n| `facts_and_sim_passage_node_unidirectional` | Facts with similarity-based passage connections (default) |\n\nGraph edges include:\n- **Fact-to-Fact edges**: Created from OpenIE extractions\n- **Synonymy edges**: Based on embedding similarity above threshold\n- **Passage edges**: Connect passages to their extracted facts\n\n## Dependencies\n\nKey package dependencies managed in `setup.py`:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `torch` | `2.5.1` | Deep learning framework |\n| `transformers` | `4.45.2` | Model architectures |\n| `vllm` | `0.6.6.post1` | LLM inference |\n| `openai` | `1.91.1` | OpenAI API client |\n| `gritlm` | `1.0.2` | GritLM embedding model |\n| `networkx` | `3.4.2` | Graph operations |\n| `python_igraph` | `0.11.8` | Graph algorithms |\n| `pydantic` | `2.10.4` | Configuration validation |\n| `tiktoken` | `0.7.0` | Tokenization |\n\n资料来源：[setup.py:15-30]()\n\n## Error Handling\n\nThe framework uses `tenacity` for retry mechanisms with configurable backoff strategies when interacting with external APIs (OpenAI, Azure, vLLM).\n\n## Persistence\n\nAll indexed data is persisted to the `save_dir` directory with the following structure:\n\n```\nsave_dir/\n└── {llm_model_name}_{embedding_model_name}/\n ├── knowledge_graph.pkl # Serialized graph\n ├── passages.pkl # Passage embeddings\n ├── fact_nodes.pkl # Extracted facts\n └── config.json # Configuration snapshot\n\n---\n\n\n\n## Knowledge Graph and Retrieval\n\n### 相关页面\n\n相关主题：[Embedding Store and Management](#page-6), [LLM Integrations](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/utils/embed_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/embed_utils.py)\n- [src/hipporag/utils/qa_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/qa_utils.py)\n- [src/hipporag/rerank.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/rerank.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/llm/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/__init__.py)\n- [src/hipporag/evaluation/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/__init__.py)\n- [src/hipporag/retrieval/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/retrieval/__init__.py)\n \n\n# Knowledge Graph and Retrieval\n\n## Overview\n\nHippoRAG implements a neurobiologically inspired retrieval system that combines knowledge graph construction with advanced retrieval algorithms. The system is designed to enable LLMs to identify and leverage connections within new knowledge for improved retrieval performance. 资料来源：[setup.py:8]()\n\nThe Knowledge Graph and Retrieval module forms the core of HippoRAG's architecture, providing mechanisms to:\n\n- Extract factual knowledge from text passages using Open Information Extraction (OpenIE)\n- Construct heterogeneous graphs with multiple node and edge types\n- Perform personalized PageRank (PPR) based retrieval over the constructed graphs\n- Support incremental updates and document deletion operations\n\n资料来源：[src/hipporag/utils/config_utils.py:48-72]()\n\n## Architecture\n\n### High-Level System Design\n\nHippoRAG's retrieval system integrates several key components working in concert to provide accurate and efficient knowledge retrieval:\n\n```mermaid\ngraph TD\n A[Input Documents] --> B[OpenIE Processing]\n B --> C[Knowledge Graph Construction]\n C --> D[Embedding Generation]\n D --> E[Synonymy Edge Building]\n C --> F[Hybrid Graph]\n \n G[Query Input] --> H[Query Embedding]\n H --> I[Personalized PageRank]\n I --> F\n F --> J[Retrieval Results]\n J --> K[Reranking]\n K --> L[Final QA Output]\n \n M[LLM Inference] --> L\n```\n\n### Graph Construction Pipeline\n\nThe graph construction process transforms raw text into a structured knowledge representation:\n\n```mermaid\ngraph LR\n A[Passages] --> B[OpenIE Extractor]\n B --> C[Triplets/Entities]\n C --> D[Fact Nodes]\n \n E[Passages] --> F[Embedding Model]\n F --> G[Passage Embeddings]\n G --> H[Passage Nodes]\n \n D --> I[Passage-Fact Edges]\n H --> I\n \n G --> J[Synonymy Edges]\n J --> K[knn Retrieval]\n K --> L[Similarity Threshold Filter]\n L --> M[Synonymy Edge Network]\n```\n\n## Knowledge Graph Components\n\n### Node Types\n\n| Node Type | Description | Attributes |\n|-----------|-------------|------------|\n| Passage Nodes | Represent original text passages | idx, title, text, embedding |\n| Fact Nodes | Extracted facts/triplets from OpenIE | subject, predicate, object, embedding |\n\n### Edge Types\n\n| Edge Type | Source | Target | Purpose |\n|-----------|--------|--------|---------|\n| Passage-to-Fact | Passage Node | Fact Node | Links passages to their extracted facts |\n| Fact-to-Fact | Fact Node | Fact Node | Connects semantically related facts |\n| Synonymy | Passage Node | Passage Node | Links passages with high semantic similarity |\n| Bidirectional | Both | Both | Full edge in both directions |\n\n资料来源：[src/hipporag/utils/config_utils.py:70-85]()\n\n### Graph Types Configuration\n\nThe system supports multiple graph configurations via the `graph_type` parameter:\n\n| Graph Type | Description |\n|------------|-------------|\n| `facts_and_sim_passage_node_unidirectional` | Facts + similar passage nodes, unidirectional edges |\n| `facts_and_sim_passage_node_bidirectional` | Facts + similar passage nodes, bidirectional edges |\n| Custom types | Extensible graph construction patterns |\n\n资料来源：[main.py:18]()\n\n## Retrieval Process\n\n### Personalized PageRank (PPR) Algorithm\n\nHippoRAG uses Personalized PageRank for graph-based retrieval, which allows queries to propagate through the knowledge graph to identify relevant nodes.\n\n```mermaid\ngraph TD\n A[Query] --> B[Query Embedding]\n B --> C[Initial PPR Scores]\n C --> D[Graph Propagation]\n D --> E{Iteration}\n E -->|Continue| F[Score Aggregation]\n F --> D\n E -->|Converge| G[Top-K Selection]\n G --> H[Linked Nodes]\n \n I[damping factor: 0.5] --> D\n J[linking_top_k: 5] --> G\n```\n\n### Retrieval Configuration Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `retrieval_top_k` | 200 | Number of documents retrieved at each step |\n| `linking_top_k` | 5 | Number of linked nodes at each retrieval step |\n| `damping` | 0.5 | Damping factor for PPR algorithm |\n| `qa_top_k` | 5 | Top-k documents fed to QA model |\n\n资料来源：[src/hipporag/utils/config_utils.py:60-72]()\n\n### Synonymy Edge Construction\n\nSynonymy edges connect passages with high semantic similarity, enabling cross-document retrieval:\n\n```mermaid\ngraph TD\n A[All Passage Embeddings] --> B[KNN Retrieval]\n B --> C[Top-K Candidates]\n C --> D{Similarity > Threshold?}\n D -->|Yes| E[Create Synonymy Edge]\n D -->|No| F[Discard]\n E --> G[Synonymy Edge Network]\n```\n\n#### Synonymy Edge Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `synonymy_edge_topk` | 2047 | k for knn retrieval in building synonymy edges |\n| `synonymy_edge_query_batch_size` | 1000 | Batch size for query embeddings |\n| `synonymy_edge_key_batch_size` | 10000 | Batch size for key embeddings |\n| `synonymy_edge_sim_threshold` | 0.8 | Similarity threshold for candidate synonymy nodes |\n\n资料来源：[src/hipporag/utils/config_utils.py:73-85]()\n\n## Embedding Integration\n\n### Embedding Model Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `embedding_model_name` | - | Name of the embedding model |\n| `embedding_batch_size` | 16 | Batch size for embedding calls |\n| `embedding_return_as_normalized` | True | Whether to normalize embeddings |\n| `embedding_max_seq_len` | 2048 | Maximum sequence length |\n| `embedding_model_dtype` | auto | Data type for local models (float16/float32/bfloat16/auto) |\n\n资料来源：[src/hipporag/utils/config_utils.py:40-54]()\n\n### Supported Embedding Models\n\nThe system integrates with multiple embedding model providers:\n\n- **NV-Embed-v2**: NVIDIA's embedding model\n- **GritLM**: GritLM embedding model\n- **Contriever**: Facebook's dense retriever\n- **OpenAI Compatible**: Any OpenAI-compatible embedding endpoint\n- **Azure OpenAI**: Azure-hosted embedding models\n\n## Reranking Module\n\nAfter initial retrieval, HippoRAG applies reranking to improve result quality. The reranking module reorders retrieved candidates using additional scoring mechanisms.\n\n```mermaid\ngraph LR\n A[Retrieved Candidates] --> B[Reranker Model]\n B --> C[Relevance Scores]\n C --> D[Ranked Results]\n D --> E[Top Results]\n```\n\n资料来源：[src/hipporag/rerank.py]()\n\n## QA Integration\n\n### Multi-Step Retrieval and Reasoning\n\nHippoRAG supports interleaved retrieval and reasoning with configurable steps:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `max_qa_steps` | 1 | Maximum steps for interleaved retrieval and reasoning |\n| `qa_top_k` | 5 | Number of documents for QA model to process |\n\n资料来源：[src/hipporag/utils/config_utils.py:68-72]()\n\n### QA Pipeline Flow\n\n```mermaid\ngraph TD\n A[Query] --> B[QA Step 1]\n B --> C[Retrieval]\n C --> D[Read Documents]\n D --> E{More Steps Needed?}\n E -->|Yes| F[Update Context]\n F --> B\n E -->|No| G[Final Answer]\n \n H[gold_docs] --> I[Evaluation]\n I --> J[Metrics]\n J --> K[Recall, EM, F1]\n```\n\n## Data Formats\n\n### Corpus JSON Structure\n\n```json\n[\n {\n \"title\": \"PASSAGE TITLE\",\n \"text\": \"PASSAGE TEXT\",\n \"idx\": 0\n }\n]\n```\n\n### Query JSON Structure\n\n```json\n[\n {\n \"id\": \"question_id\",\n \"question\": \"QUESTION TEXT\",\n \"answer\": [\"ANSWER\"],\n \"answerable\": true,\n \"paragraphs\": [\n {\n \"title\": \"SUPPORTING TITLE\",\n \"text\": \"SUPPORTING TEXT\",\n \"is_supporting\": true,\n \"idx\": 0\n }\n ]\n }\n]\n```\n\n## Usage Examples\n\n### Basic Retrieval with 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# Index documents\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\nhipporag.index(docs)\n\n# Query with evaluation\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资料来源：[README.md:Quick_Start](), [tests_openai.py:22-60]()\n\n### Incremental Updates\n\n```python\n# Add new documents\nnew_docs = [\n \"Tom Hort's birthplace is Montebello.\",\n \"Sam Hort's birthplace is Montebello.\"\n]\nhipporag.index(docs=new_docs)\n\n# Delete documents\ndocs_to_delete = [\n \"Tom Hort's birthplace is Montebello.\",\n \"Sam Hort's birthplace is Montebello.\"\n]\nhipporag.delete(docs_to_delete)\n```\n\n资料来源：[tests_openai.py:61-82]()\n\n## Evaluation Metrics\n\nThe retrieval system is evaluated using standard information retrieval metrics:\n\n| Metric | Description |\n|--------|-------------|\n| Recall@k | Fraction of relevant documents in top-k |\n| EM | Exact Match accuracy |\n| F1 | Harmonic mean of precision and recall |\n\n## Summary\n\nThe Knowledge Graph and Retrieval module in HippoRAG provides a sophisticated pipeline for:\n\n1. **Knowledge Extraction**: Using OpenIE to extract factual triplets from text\n2. **Graph Construction**: Building heterogeneous graphs with passage nodes, fact nodes, and multiple edge types\n3. **Synonymy Discovery**: Creating semantic links between similar passages via embedding similarity\n4. **PPR-based Retrieval**: Performing personalized PageRank for graph-aware document retrieval\n5. **Reranking**: Refining retrieval results for improved accuracy\n6. **Incremental Updates**: Supporting document additions and deletions\n\nThis architecture enables HippoRAG to perform complex associativity and multi-hop reasoning tasks that traditional vector similarity retrieval cannot accomplish effectively.\n\n---\n\n\n\n## Embedding Store and Management\n\n### 相关页面\n\n相关主题：[LLM Integrations](#page-7), [Embedding Models](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/embedding_store.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_store.py)\n- [src/hipporag/utils/embed_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/embed_utils.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/embedding_model/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/__init__.py)\n- [src/hipporag/embedding_model/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/base.py)\n \n\n# Embedding Store and Management\n\n## Overview\n\nThe Embedding Store and Management system in HippoRAG provides a unified interface for encoding text passages into vector embeddings, managing these embeddings throughout the indexing and retrieval lifecycle, and supporting multiple embedding model backends including NVIDIA NV-Embed-v2, GritLM, and Contriever. The system is designed to handle batch processing of documents with configurable parameters for sequence length, data type precision, and normalization behavior.\n\nHippoRAG's embedding management is tightly integrated with the knowledge graph construction process, where embeddings serve dual purposes: enabling semantic similarity search for passage linking and powering the retrieval phase through Personalized PageRank (PPR) algorithms. The embedding store abstracts away the underlying model implementation details, allowing the framework to switch between different embedding providers without changing the core indexing and retrieval logic.\n\n资料来源：[src/hipporag/utils/config_utils.py:1-50]()\n\n## Architecture\n\n### High-Level Components\n\nThe embedding system consists of three primary layers that work together to provide embedding services throughout the HippoRAG pipeline.\n\nThe **Model Layer** contains implementations for specific embedding models, each inheriting from a common base class that enforces a consistent interface. Currently supported models include NV-Embed-v2, GritLM, and Contriever, with the architecture supporting easy extension to additional models. Each model implementation handles the specific requirements of its underlying transformer architecture, including tokenizer configuration, padding strategies, and model-specific inference optimizations.\n\nThe **Utility Layer** provides helper functions for common embedding operations such as batch processing, embedding normalization, and similarity computation. These utilities ensure consistent handling of embeddings across different contexts and help optimize memory usage during large-scale indexing operations.\n\nThe **Configuration Layer** defines the parameters that control embedding behavior, including batch sizes, sequence length limits, and model-specific settings. This layer connects the embedding system to HippoRAG's global configuration management, allowing users to customize embedding behavior without modifying code.\n\n```mermaid\ngraph TD\n A[Documents] --> B[Embedding Store]\n B --> C[Model Layer
NV-Embed-v2
GritLM
Contriever]\n B --> D[Utility Layer
Batch Processing
Normalization]\n C --> E[Vector Storage]\n D --> E\n E --> F[Graph Construction]\n E --> G[Retrieval Phase]\n```\n\n资料来源：[src/hipporag/embedding_store.py:1-30]()\n\n### Data Flow\n\nDuring the **indexing phase**, documents are first processed by the embedding store to generate passage vectors. These vectors are stored alongside the passage metadata and serve as the foundation for graph construction. The embedding store processes passages in configurable batch sizes to balance memory usage and throughput, with the default batch size set to 16 documents per batch.\n\nDuring the **retrieval phase**, incoming queries are encoded using the same embedding model to produce a query vector. This query vector is then used for similarity computation against the indexed passage vectors, enabling semantic matching between the query intent and stored knowledge. The retrieval system can perform k-nearest neighbor (kNN) searches over the embedding space to identify candidate passages for further processing.\n\n```mermaid\ngraph LR\n A[Indexing Flow] --> B[Input Documents]\n B --> C[Batch Processing
batch_size=16]\n C --> D[Embedding Encoding]\n D --> E[Normalized Vectors]\n E --> F[Vector Storage]\n \n G[Retrieval Flow] --> H[Query Text]\n H --> I[Query Encoding]\n I --> J[Similarity Search]\n J --> K[kNN Retrieval
top-k candidates]\n K --> L[Ranked Passages]\n```\n\n资料来源：[src/hipporag/utils/embed_utils.py:1-25]()\n\n## Configuration Parameters\n\nThe embedding system is controlled through several configuration parameters defined in the global configuration structure. These parameters allow fine-tuning of embedding behavior for different hardware configurations and use cases.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `embedding_batch_size` | int | 16 | Number of documents processed in each embedding batch |\n| `embedding_return_as_normalized` | bool | true | Whether to L2-normalize output embeddings |\n| `embedding_max_seq_len` | int | 2048 | Maximum sequence length in tokens for the embedding model |\n| `embedding_model_dtype` | Literal | \"auto\" | Data type for local embedding models: float16, float32, bfloat16, or auto |\n| `embedding_model_name` | str | varies | Identifier for the embedding model (e.g., \"nvidia/NV-Embed-v2\") |\n| `embedding_base_url` | str | None | Base URL for OpenAI-compatible embedding endpoints |\n| `synonymy_edge_topk` | int | 2047 | k value for kNN retrieval when building synonymy edges |\n| `synonymy_edge_sim_threshold` | float | 0.8 | Minimum similarity threshold for synonymy edge candidates |\n\n资料来源：[src/hipporag/utils/config_utils.py:15-40]()\n\n## Embedding Model Interface\n\n### Base Class Contract\n\nAll embedding models must inherit from `BaseEmbeddingModel`, which defines the core interface that HippoRAG expects. The base class enforces implementation of the `__call__` method that accepts text inputs and returns embeddings, ensuring polymorphism across different model implementations.\n\nThe base class also defines the `EmbeddingConfig` dataclass that encapsulates model-specific settings. This configuration includes the model name, batch size, maximum sequence length, and data type settings. The configuration object is passed to the embedding model during initialization and can be modified to adjust model behavior without recreating the model instance.\n\n### Supported Models\n\n**NV-Embed-v2** is the primary embedding model recommended for production use, developed by NVIDIA. It provides high-quality sentence embeddings optimized for retrieval tasks. The model is accessed through HuggingFace and supports automatic device placement based on available GPU resources.\n\n**GritLM** provides an alternative embedding approach that combines retrieval and generation capabilities. It can serve both as an embedding model and as a decoder for generation tasks, offering flexibility in deployment configurations.\n\n**Contriever** is an open-source bi-encoder model for dense retrieval, useful for scenarios requiring a completely open-source embedding solution without proprietary dependencies.\n\n资料来源：[src/hipporag/embedding_model/__init__.py:1-20]()\n\n## Embedding Store API\n\n### Initialization\n\nThe embedding store is typically instantiated through the main HippoRAG class rather than directly. When creating a HippoRAG instance, the embedding model name and optional endpoint configuration are passed as parameters:\n\n```python\nhipporag = HippoRAG(\n save_dir=\"outputs\",\n llm_model_name=\"gpt-4o-mini\",\n embedding_model_name=\"nvidia/NV-Embed-v2\"\n)\n```\n\nFor OpenAI-compatible embedding endpoints, the base URL can be specified:\n\n```python\nhipporag = HippoRAG(\n save_dir=\"outputs\",\n llm_model_name=\"gpt-4o-mini\",\n embedding_model_name=\"text-embedding-3-small\",\n embedding_base_url=\"https://api.openai.com/v1\"\n)\n```\n\n资料来源：[README.md:1-50]()\n\n### Encoding Operations\n\nThe embedding store provides batch encoding capabilities for processing multiple documents efficiently. The encoding operation returns normalized embeddings by default, which is required for proper similarity computation during retrieval. The normalization is L2 normalization, ensuring that all embedding vectors have unit length.\n\nFor Azure OpenAI deployments, specialized endpoint parameters are supported:\n\n```python\nhipporag = HippoRAG(\n save_dir=\"save_dir\",\n llm_model_name=\"gpt-4o-mini\",\n embedding_model_name=\"text-embedding-3-small\",\n azure_endpoint=\"https://[ENDPOINT].openai.azure.com/...\",\n azure_embedding_endpoint=\"https://[ENDPOINT].openai.azure.com/...\"\n)\n```\n\n资料来源：[demo_azure.py:1-30]()\n\n## Integration with Knowledge Graph\n\nThe embedding system plays a critical role in HippoRAG's knowledge graph construction phase. After passages are indexed and encoded, the embeddings are used for two key graph-related operations.\n\n**Synonymy Edge Construction** uses embeddings to identify semantically similar passage pairs that should be connected in the knowledge graph. The system performs k-nearest neighbor searches over the passage embedding space, where the `synonymy_edge_topk` parameter controls how many candidates are considered for each passage. The `synonymy_edge_sim_threshold` parameter filters these candidates, with only pairs exceeding the similarity threshold being connected as synonymy edges.\n\n**Retrieval-Graph Linking** during the PPR retrieval process uses passage embeddings to establish the connection between the query and the knowledge graph. The query embedding enables the system to identify the most relevant starting nodes in the graph for the random walk algorithm.\n\n资料来源：[src/hipporag/utils/config_utils.py:30-45]()\n\n## Memory Management and Optimization\n\n### Batch Processing Strategy\n\nThe embedding store implements batch processing to optimize GPU memory utilization and throughput. The batch size is configurable via `embedding_batch_size` with a default of 16, meaning 16 documents are processed simultaneously during encoding. For systems with larger GPU memory, increasing this value can significantly improve indexing performance.\n\nThe system also supports separate batch sizes for the synonymy edge construction phase. The `synonymy_edge_query_batch_size` (default 1000) controls how many passage embeddings are queried at once during kNN search, while `synonymy_edge_key_batch_size` (default 10000) controls the key batch size for the search index.\n\n### Data Type Selection\n\nThe `embedding_model_dtype` parameter allows selection of the precision for local embedding models. The \"auto\" setting allows the system to select an appropriate default based on the hardware and model. Available options include float16 for memory-constrained environments, float32 for maximum precision, and bfloat16 which offers a good balance of range and memory efficiency on newer GPUs.\n\n资料来源：[src/hipporag/utils/config_utils.py:25-35]()\n\n## Error Handling and Resilience\n\nThe embedding system is designed with error handling patterns compatible with HippoRAG's overall resilience strategy. Batch processing allows partial failures to be identified and retried without losing all progress. The configuration system supports specifying fallback models or endpoints for production deployments requiring high availability.\n\nTenacity is used for retry logic in the embedding utilities, ensuring transient network failures or temporary service unavailability do not cause complete pipeline failures. This is particularly important when using remote embedding endpoints that may experience temporary connectivity issues.\n\n资料来源：[setup.py:1-30]()\n\n## Performance Considerations\n\nWhen optimizing HippoRAG for production deployment, the embedding configuration should be tuned based on the available hardware and expected workload characteristics. The primary tuning parameters include batch size for indexing throughput, sequence length limits for handling long documents, and data type selection for memory-constrained environments.\n\nFor maximum retrieval quality, the default normalization behavior should be maintained as it ensures consistent similarity computation across the retrieval pipeline. Disabling normalization may lead to suboptimal retrieval results as the similarity metrics assume unit-normalized vectors.\n\n资料来源：[src/hipporag/utils/config_utils.py:18-22]()\n\n## Related Components\n\nThe embedding system interacts closely with several other HippoRAG components. The Information Extraction module uses embeddings for processing extracted facts, the retrieval module depends on embeddings for kNN search and PPR initialization, and the evaluation module uses embeddings for computing retrieval metrics such as recall and MRR.\n\nThe embedding model implementations in `src/hipporag/embedding_model/` follow a consistent interface defined in `base.py`, allowing the embedding store to work with any model that adheres to this contract.\n\n---\n\n\n\n## LLM Integrations\n\n### 相关页面\n\n相关主题：[Embedding Models](#page-8), [Deployment Options](#page-10)\n\n\nRelevant Source Files
\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 \n\n# LLM Integrations\n\nHippoRAG provides a flexible, pluggable architecture for integrating various Large Language Model (LLM) providers. This modular design enables the framework to support multiple inference backends including OpenAI, vLLM for local deployment, and AWS Bedrock, allowing researchers and developers to choose the most appropriate LLM backend for their specific use case and infrastructure requirements.\n\n## Architecture Overview\n\nThe LLM integration system follows a strategy pattern where a base abstract class defines the interface contract, and concrete implementations handle provider-specific details. This design ensures that the core HippoRAG logic remains independent of any particular LLM vendor while maintaining the ability to leverage specialized features offered by different providers.\n\n```mermaid\ngraph TD\n A[HippoRAG Core] --> B[LLM Base Class]\n B --> C[OpenAIGPT]\n B --> D[VLLMOffline]\n B --> E[BedrockLLM]\n B --> F[Custom LLM Adapter]\n \n C --> G[OpenAI API]\n D --> H[Local vLLM Server]\n E --> I[AWS Bedrock]\n```\n\nThe `BaseLLM` abstract class in `src/hipporag/llm/base.py` defines the common interface that all LLM adapters must implement, ensuring consistent behavior across different providers.\n\n## Supported LLM Providers\n\n### OpenAI Models\n\nHippoRAG supports all OpenAI chat completion models through the `OpenAIGPT` class. This integration allows users to leverage the GPT family of models for both information extraction and question answering tasks.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model_name` | string | required | OpenAI model identifier (e.g., `gpt-4o-mini`, `gpt-4o`) |\n| `api_key` | string | env `OPENAI_API_KEY` | OpenAI API authentication key |\n| `base_url` | string | `https://api.openai.com/v1` | API endpoint base URL |\n| `max_tokens` | int | `None` | Maximum tokens in generated response |\n| `temperature` | float | `0.0` | Sampling temperature for generation |\n\n**Usage Example:**\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\n资料来源：[README.md:67-72](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### vLLM Local Deployment\n\nFor scenarios requiring local inference, HippoRAG supports vLLM-deployed models through the `VLLMOffline` class. This approach is particularly useful for privacy-sensitive applications, cost reduction at scale, or when working with custom fine-tuned models.\n\n**Server Setup:**\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.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:93-101](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n**Configuration Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model_name` | string | required | Model identifier for vLLM server |\n| `base_url` | string | required | vLLM server endpoint URL |\n| `openie_mode` | string | `\"online\"` | Mode for OpenIE processing (`online` or `offline`) |\n| `max_tokens` | int | `None` | Maximum tokens in generated response |\n| `temperature` | float | `0.0` | Sampling temperature for generation |\n\n**Offline Mode for OpenIE:**\n\nThe vLLM integration supports an offline mode where OpenIE extraction runs separately from the main pipeline. This is useful for debugging or when OpenIE results can be cached and reused.\n\n```python\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资料来源：[README.md:130-135](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### AWS Bedrock\n\nHippoRAG integrates with AWS Bedrock through the `BedrockLLM` class, enabling access to various foundation models hosted on AWS infrastructure. This integration is designed for enterprise deployments requiring scalable, managed LLM services.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model_name` | string | required | Bedrock model identifier |\n| `aws_region` | string | `\"us-east-1\"` | AWS region for Bedrock endpoint |\n| `max_tokens` | int | `None` | Maximum tokens in generated response |\n| `temperature` | float | `0.0` | Sampling temperature for generation |\n\n### Azure OpenAI\n\nFor enterprise users with Azure OpenAI deployments, HippoRAG provides direct integration with Azure endpoints.\n\n**Configuration Example:**\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='gpt-4o-mini',\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资料来源：[demo_azure.py:16-21](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.py)\n\n## Base LLM Interface\n\nAll LLM adapters inherit from the `BaseLLM` abstract class, which defines the core contract for LLM interactions.\n\n```mermaid\nclassDiagram\n class BaseLLM {\n <>\n +generate(prompt: str) str\n +batch_generate(prompts: List[str]) List[str]\n +get_model_name() str\n }\n \n class OpenAIGPT {\n +generate(prompt: str) str\n +batch_generate(prompts: List[str]) List[str]\n }\n \n class VLLMOffline {\n +generate(prompt: str) str\n +batch_generate(prompts: List[str]) List[str]\n }\n \n class BedrockLLM {\n +generate(prompt: str) str\n +batch_generate(prompts: List[str]) List[str]\n }\n \n BaseLLM <|-- OpenAIGPT\n BaseLLM <|-- VLLMOffline\n BaseLLM <|-- BedrockLLM\n```\n\n**Core Methods:**\n\n| Method | Parameters | Return Type | Description |\n|--------|------------|-------------|-------------|\n| `generate` | `prompt: str` | `str` | Generate a single response from a prompt |\n| `batch_generate` | `prompts: List[str]` | `List[str]` | Generate responses for multiple prompts in batch |\n| `get_model_name` | None | `str` | Return the configured model identifier |\n\n## OpenIE Integration\n\nOpen Information Extraction (OpenIE) is a critical component of HippoRAG's knowledge graph construction pipeline. The LLM integration system supports multiple OpenIE modes to accommodate different deployment scenarios.\n\n```mermaid\ngraph LR\n A[Documents] --> B{HippoRAG}\n B --> C{OpenIE Mode}\n \n C -->|online| D[Real-time OpenIE]\n C -->|offline| E[Cached OpenIE Results]\n \n D --> F[OpenIE with LLM]\n E --> G[Load from JSON]\n \n F --> H[Knowledge Graph]\n G --> H\n```\n\n**OpenIE Implementation Classes:**\n\n| Class | Provider | Use Case |\n|-------|----------|----------|\n| `OpenAI_GPT` | OpenAI API | Cloud-based OpenIE extraction |\n| `VLLM_Offline` | Local vLLM | Private/onsite OpenIE extraction |\n\n资料来源：[README.md:47-48](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Configuration Schema\n\nThe LLM integration configuration is defined through the `HippoRAGConfig` class, which validates and manages all LLM-related settings.\n\n**Configuration Fields:**\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `llm_name` | string | required | LLM model identifier |\n| `llm_base_url` | string | `None` | Base URL for LLM API endpoint |\n| `llm_max_tokens` | int | `None` | Maximum tokens per generation |\n| `llm_temperature` | float | `0.0` | Sampling temperature |\n| `openie_mode` | string | `\"online\"` | OpenIE processing mode |\n| `skip_graph` | bool | `False` | Skip graph construction step |\n\n资料来源：[main.py:18-26](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n## Workflow Integration\n\nThe following diagram illustrates how LLM integrations fit into the HippoRAG indexing and retrieval pipeline:\n\n```mermaid\ngraph TD\n subgraph Indexing\n A1[Input Documents] --> A2[Chunking]\n A2 --> A3[Embedding Generation]\n A3 --> A4[OpenIE with LLM]\n A4 --> A5[Knowledge Graph Construction]\n A5 --> A6[Graph Indexing]\n end\n \n subgraph Retrieval & QA\n B1[User Query] --> B2[Query Embedding]\n B2 --> B3[Graph Traversal]\n B3 --> B4[LLM for Answer Synthesis]\n B4 --> B5[Final Answer]\n end\n \n A4 -.->|Uses| LLM1[LLM Adapter]\n B4 -.->|Uses| LLM1\n```\n\n## Environment Variables\n\nProper configuration of environment variables is essential for LLM integrations to function correctly.\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OPENAI_API_KEY` | For OpenAI | OpenAI API authentication key |\n| `HF_HOME` | For vLLM | Hugging Face cache directory |\n| `CUDA_VISIBLE_DEVICES` | For GPU | Comma-separated GPU device IDs |\n| `AWS_ACCESS_KEY_ID` | For Bedrock | AWS access credentials |\n| `AWS_SECRET_ACCESS_KEY` | For Bedrock | AWS secret credentials |\n\n资料来源：[README.md:58-66](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Testing LLM Integrations\n\nHippoRAG provides dedicated test scripts to verify LLM integration functionality.\n\n### OpenAI Test\n\n```bash\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n### Local vLLM Test\n\n```bash\n# Terminal 1: Start vLLM server\nexport CUDA_VISIBLE_DEVICES=0\nvllm serve meta-llama/Llama-3.1-8B-Instruct --port 6578\n\n# Terminal 2: Run test\nCUDA_VISIBLE_DEVICES=1 python tests_local.py\n```\n\n资料来源：[README.md:137-148](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Error Handling and Retries\n\nThe LLM integrations leverage the `tenacity` library for automatic retry behavior with exponential backoff. This ensures robust operation when dealing with network issues or rate limiting from LLM providers.\n\nConfiguration options for retry behavior:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `max_attempts` | 3 | Maximum number of retry attempts |\n| `wait_exponential_multiplier` | 1000 | Initial wait time in milliseconds |\n| `wait_exponential_max` | 10000 | Maximum wait time in milliseconds |\n\n## Extending LLM Support\n\nTo add support for a new LLM provider, implement a new class that inherits from `BaseLLM` and implements the required abstract methods:\n\n```python\nfrom hipporag.llm.base import BaseLLM\n\nclass CustomLLM(BaseLLM):\n def __init__(self, model_name: str, **kwargs):\n self.model_name = model_name\n # Initialize provider-specific client\n \n def generate(self, prompt: str) -> str:\n # Implement generation logic\n pass\n \n def batch_generate(self, prompts: List[str]) -> List[str]:\n # Implement batch generation\n pass\n \n def get_model_name(self) -> str:\n return self.model_name\n```\n\n## Performance Considerations\n\nWhen selecting and configuring LLM integrations, consider the following factors:\n\n1. **Latency**: OpenAI APIs typically offer lower latency for small workloads, while vLLM provides better performance for high-throughput scenarios\n2. **Cost**: Local vLLM deployment eliminates API costs but requires GPU infrastructure\n3. **Privacy**: For sensitive data, local deployment via vLLM or Bedrock private endpoints is recommended\n4. **Model Size**: Larger models (e.g., Llama-3.3-70B) require more GPU memory but often provide better extraction quality\n\n---\n\n\n\n## Embedding Models\n\n### 相关页面\n\n相关主题：[Embedding Store and Management](#page-6), [LLM Integrations](#page-7)\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/__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 \n\n# Embedding Models\n\nHippoRAG provides a flexible, modular embedding model system that supports multiple embedding backends including NVIDIA's NV-Embed-v2, GritLM, HuggingFace Transformers, and vLLM endpoints. This modular architecture enables the system to generate high-quality text embeddings for both passage encoding and query understanding in the retrieval pipeline.\n\n## Architecture Overview\n\nThe embedding model subsystem follows a base class pattern with specialized implementations. All embedding models inherit from `BaseEmbeddingModel` which defines the common interface and configuration schema.\n\n```mermaid\ngraph TD\n A[HippoRAG Core] --> B[Embedding Model Factory]\n B --> C[BaseEmbeddingModel]\n C --> D[NVEmbedV2]\n C --> E[GritLM]\n C --> F[TransformersEmbeddingModel]\n C --> G[VLLMEmbeddingModel]\n```\n\nThe factory pattern in `__init__.py` dynamically instantiates the appropriate embedding model based on the model name prefix:\n\n| Prefix | Model Class | Backend |\n|--------|-------------|---------|\n| `nvidia/NV-Embed-v2` | `NVEmbedV2` | HuggingFace |\n| `GritLM` | `GritLM` | GritLM library |\n| `Transformers/` | `TransformersEmbeddingModel` | SentenceTransformers |\n| `VLLM/` | `VLLMEmbeddingModel` | vLLM endpoints |\n\n资料来源：[src/hipporag/embedding_model/__init__.py](src/hipporag/embedding_model/__init__.py)\n\n## Base Configuration\n\nThe `BaseEmbeddingModel` and `EmbeddingConfig` classes define the configuration schema used across all embedding implementations. Configuration parameters include:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `embedding_batch_size` | 16 | Batch size for encoding operations |\n| `embedding_return_as_normalized` | True | Whether to normalize output embeddings |\n| `embedding_max_seq_len` | 2048 | Maximum sequence length for tokenization |\n| `embedding_model_dtype` | \"auto\" | Data type: float16, float32, bfloat16, or auto |\n\n资料来源：[src/hipporag/utils/config_utils.py:16-35](src/hipporag/utils/config_utils.py)\n\n## Available Embedding Models\n\n### NV-Embed-v2\n\nThe `NVEmbedV2` class provides integration with NVIDIA's NV-Embed-v2 embedding model, a high-performance encoder optimized for retrieval tasks.\n\n```python\nclass NVEmbedV2(BaseEmbeddingModel):\n def __init__(self, global_config: BaseConfig, embedding_model_name: str) -> None:\n super().__init__(global_config=global_config)\n # Model initialization with HuggingFace transformers\n```\n\n资料来源：[src/hipporag/embedding_model/NVEmbedV2.py](src/hipporag/embedding_model/NVEmbedV2.py)\n\n### GritLM\n\nThe `GritLM` class wraps the GritLM library for generating embeddings with built-in instruction-following capabilities.\n\n```python\nclass GritLM(BaseEmbeddingModel):\n def __init__(self, global_config: BaseConfig, embedding_model_name: str) -> None:\n super().__init__(global_config=global_config)\n # GritLM-specific initialization\n```\n\n资料来源：[src/hipporag/embedding_model/GritLM.py](src/hipporag/embedding_model/GritLM.py)\n\n### Transformers (SentenceTransformers)\n\nThe `TransformersEmbeddingModel` class enables using any model from the HuggingFace ecosystem via the SentenceTransformers library. Select this implementation by using `embedding_model_name` that starts with `\"Transformers/\"`.\n\n```python\nclass TransformersEmbeddingModel(BaseEmbeddingModel):\n \"\"\"\n To select this implementation you can initialise HippoRAG with:\n embedding_model_name starts with \"Transformers/\"\n \"\"\"\n def __init__(self, global_config: BaseConfig, embedding_model_name: str) -> None:\n super().__init__(global_config=global_config)\n self.model_id = embedding_model_name[len(\"Transformers/\"):]\n self.batch_size = 64\n self.model = SentenceTransformer(\n self.model_id, \n device=\"cuda\" if torch.cuda.is_available() else \"cpu\"\n )\n```\n\nKey characteristics:\n- Automatically detects CUDA availability for GPU acceleration\n- Uses batch size of 64 for efficient processing\n- Extracts model ID by removing the `\"Transformers/\"` prefix\n\n资料来源：[src/hipporag/embedding_model/Transformers.py:1-40](src/hipporag/embedding_model/Transformers.py)\n\n### VLLM (Endpoint-based)\n\nThe `VLLMEmbeddingModel` class provides integration with OpenAI-compatible vLLM embedding endpoints. Select this implementation by using `embedding_model_name` that starts with `\"VLLM/\"`.\n\n```python\nclass VLLMEmbeddingModel(BaseEmbeddingModel):\n \"\"\"\n To select this implementation you can initialise HippoRAG with:\n embedding_model_name starts with \"VLLM/\"\n The embedding base url should contain the v1/embeddings.\n \"\"\"\n def __init__(self, global_config: BaseConfig, embedding_model_name: str) -> None:\n super().__init__(global_config=global_config)\n self.model_id = embedding_model_name[len(\"VLLM/\"):]\n self.batch_size = 32\n self.url = global_config.embedding_base_url\n```\n\nThe model communicates with the endpoint using the OpenAI embeddings API format:\n\n```python\npayload = {\n \"model\": self.model_id,\n \"input\": input_text,\n}\nresponse = requests.post(self.base_url, headers=headers, json=payload)\n```\n\n资料来源：[src/hipporag/embedding_model/VLLM.py:1-50](src/hipporag/embedding_model/VLLM.py)\n\n## Query Instructions\n\nEmbedding models support query instruction templates for improving retrieval relevance. The system uses instructions for mapping queries to facts and passages:\n\n```python\nself.search_query_instr = set([\n get_query_instruction('query_to_fact'),\n get_query_instruction('query_to_passage')\n])\n```\n\n资料来源：[src/hipporag/embedding_model/Transformers.py:23-27](src/hipporag/embedding_model/Transformers.py)\n\n## Usage Patterns\n\n### Quick Start with OpenAI-style Models\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\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\n### Using Custom Endpoints\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### Using vLLM Local Deployment\n\n```python\n# Start vLLM server\nvllm serve meta-llama/Llama-3.1-8B-Instruct --tensor-parallel-size 2\n\n# Configure with VLLM prefix\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='...',\n embedding_model_name='VLLM/your-model-name',\n embedding_base_url='http://localhost:8000/v1/embeddings'\n)\n```\n\n## Dependencies\n\nThe embedding model system depends on the following packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `transformers` | 4.45.2 | Core model loading |\n| `sentence-transformers` | (via Transformers) | Sentence encoding |\n| `gritlm` | 1.0.2 | GritLM embeddings |\n| `torch` | 2.5.1 | GPU acceleration |\n| `einops` | (latest) | Tensor operations |\n\n资料来源：[setup.py:19-32](setup.py)\n\n## Configuration Parameters Summary\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `embedding_batch_size` | int | 16 | Batch size for embedding inference |\n| `embedding_return_as_normalized` | bool | True | L2 normalize embeddings |\n| `embedding_max_seq_len` | int | 2048 | Maximum token sequence length |\n| `embedding_model_dtype` | str | \"auto\" | Model precision (float16/float32/bfloat16/auto) |\n\n资料来源：[src/hipporag/utils/config_utils.py:16-29](src/hipporag/utils/config_utils.py)\n\n---\n\n\n\n## Open Information Extraction (OpenIE)\n\n### 相关页面\n\n相关主题：[Knowledge Graph and Retrieval](#page-5), [LLM Integrations](#page-7)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.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\n \n\n# Open Information Extraction (OpenIE)\n\n## Overview\n\nOpen Information Extraction (OpenIE) is a critical component in the HippoRAG pipeline that enables the extraction of structured knowledge triples from unstructured text. The system extracts **entities**, **relations**, and **triples** from passages to construct a knowledge graph that mimics hippocampal memory formation in biological systems.\n\nIn HippoRAG, OpenIE serves as the foundation for building the associative memory graph. Extracted triples form **fact nodes** in the knowledge graph, enabling parametric nearest neighbor (PPR) retrieval that connects related information across documents.\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Architecture\n\nThe OpenIE system in HippoRAG supports multiple deployment modes and LLM backends:\n\n```mermaid\ngraph TD\n A[Unstructured Text] --> B[Information Extraction Module]\n B --> C{openie_mode}\n C -->|online| D[OpenAI GPT]\n C -->|offline| E[vLLM Offline]\n D --> F[Triple Extraction]\n E --> F\n F --> G[NER Processing]\n G --> H[Knowledge Triples]\n H --> I[Knowledge Graph Construction]\n```\n\n### Module Structure\n\n| Module | File | Purpose |\n|--------|------|---------|\n| Base Interface | `information_extraction/__init__.py` | Exports model classes |\n| OpenAI Integration | `openie_openai_gpt.py` | Online OpenIE via OpenAI API |\n| vLLM Offline | `openie_vllm_offline.py` | Offline batch processing with vLLM |\n| Triple Extraction Prompt | `prompts/templates/triple_extraction.py` | LLM prompt for triple extraction |\n| NER Prompt | `prompts/templates/ner.py` | LLM prompt for named entity recognition |\n\n资料来源：[README.md - Code Structure](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Configuration\n\n### ConfigUtils Class Parameters\n\nThe `InformationExtractionConfig` dataclass provides the following configuration options:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `information_extraction_model_name` | `Literal[\"openie_openai_gpt\"]` | `\"openie_openai_gpt\"` | Class name indicating which information extraction model to use |\n| `openie_mode` | `Literal[\"offline\", \"online\"]` | `\"online\"` | Mode of the OpenIE model: `online` uses OpenAI API, `offline` uses vLLM batch processing |\n| `skip_graph` | `bool` | `False` | Whether to skip graph construction. Set to `True` when running vLLM offline indexing for the first time |\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### Main Entry Point Configuration\n\nIn the `main.py` script, OpenIE parameters are passed via command-line arguments:\n\n```python\nconfig = BaseConfig(\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 max_new_tokens=None,\n corpus_len=len(corpus),\n openie_mode=args.openie_mode # 'online' or 'offline'\n)\n```\n\n**Command-line arguments:**\n- `--openie_mode`: Choose between `online` (OpenAI API) or `offline` (vLLM)\n- `--force_openie_from_scratch`: If `False`, reuse existing OpenIE results if available\n\n资料来源：[main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n## Extraction Workflow\n\n### Triple Extraction Process\n\nThe triple extraction workflow follows these steps:\n\n```mermaid\nsequenceDiagram\n participant Text as Raw Text Input\n participant Triple as Triple Extraction Prompt\n participant LLM as Language Model\n participant NER as NER Prompt\n participant Output as Knowledge Triples\n \n Text->>Triple: Passage text\n Triple->>LLM: Structured prompt\n LLM->>Output: Subject-Predicate-Object triples\n Output->>NER: Named Entity Recognition\n NER->>LLM: Entity labels\n LLM->>Output: Typed entities\n```\n\n### Supported Deployment Modes\n\n| Mode | Backend | Use Case | API Key Required |\n|------|---------|----------|------------------|\n| `online` | OpenAI GPT | Quick testing, small corpora | Yes (`OPENAI_API_KEY`) |\n| `offline` | vLLM | Large-scale indexing, cost efficiency | No (local deployment) |\n\n## Knowledge Graph Integration\n\nOpenIE extracted triples are converted into graph structures:\n\n```mermaid\ngraph LR\n A[Passage Text] -->|OpenIE| B[Triple: Entity1 → Relation → Entity2]\n B --> C[Fact Node]\n C --> D[Knowledge Graph]\n D --> E[Personalized PageRank]\n E --> F[Associative Retrieval]\n```\n\nThe extracted triples serve dual purposes:\n\n1. **Fact Nodes**: Create direct connections between related entities\n2. **Association Links**: Enable multi-hop reasoning through the graph\n\nThis design mirrors the dentate gyrus pattern separation mechanism in the hippocampus, where similar memories are differentiated to reduce interference.\n\n资料来源：[README.md - Methodology](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Usage Examples\n\n### Online Mode (OpenAI)\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# OpenIE runs automatically during indexing\nhipporag.index(docs=[\"Passage containing facts to extract.\"])\n```\n\n### Offline Mode (vLLM)\n\n```bash\n# 1. Start vLLM server\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\n# 2. Run indexing with offline OpenIE\npython main.py --dataset sample --openie_mode offline\n```\n\n资料来源：[README.md - Quick Start](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Dependencies\n\nThe OpenIE system requires the following core dependencies:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `torch` | 2.5.1 | PyTorch backend |\n| `transformers` | 4.45.2 | Model architecture |\n| `openai` | 1.91.1 | Online OpenAI API |\n| `vllm` | 0.6.6.post1 | Offline inference |\n| `litellm` | 1.73.1 | Unified LLM interface |\n| `tqdm` | - | Progress bars |\n\n资料来源：[setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n\n## Extracted Data Format\n\nOpenIE produces structured triples in the following format:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `subject` | str | First entity |\n| `predicate` | str | Relation verb/phrase |\n| `object` | str | Second entity |\n| `context` | str | Source passage text |\n\nThese triples are then processed into graph nodes and edges for the knowledge graph construction phase.\n\n---\n\n\n\n## Deployment Options\n\n### 相关页面\n\n相关主题：[Installation and Setup](#page-1), [LLM Integrations](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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- [demo_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.py)\n- [demo_local.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_local.py)\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- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n \n\n# Deployment Options\n\nHippoRAG supports multiple deployment configurations to accommodate different infrastructure requirements and use cases. This page documents the available deployment options, configuration parameters, and setup procedures for running HippoRAG in various environments.\n\n## Overview\n\nHippoRAG provides three primary deployment models:\n\n| Deployment Type | LLM Backend | Embedding Backend | Typical Use Case |\n|-----------------|-------------|-------------------|------------------|\n| **OpenAI API** | OpenAI hosted models | OpenAI/NVIDIA hosted | Quickstart, development |\n| **vLLM (Local)** | Self-hosted LLMs via vLLM | Local embedding models | Production, cost-sensitive |\n| **Azure OpenAI** | Azure-hosted models | Azure-hosted embeddings | Enterprise compliance |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Environment Setup\n\nRegardless of deployment type, certain environment variables must be configured:\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\n```\n\nFor OpenAI and Azure deployments, additional API credentials are required:\n\n```bash\nexport OPENAI_API_KEY=\n```\n\n资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## OpenAI API Deployment\n\nThe simplest deployment option uses OpenAI's hosted API endpoints for both LLM inference and embeddings.\n\n### Configuration Parameters\n\n| Parameter | Description | Example Value |\n|-----------|-------------|---------------|\n| `--llm_base_url` | OpenAI API endpoint | `https://api.openai.com/v1` |\n| `--llm_name` | OpenAI model identifier | `gpt-4o-mini` |\n| `--embedding_name` | Embedding model name | `nvidia/NV-Embed-v2` |\n\n### Running with OpenAI Models\n\n```bash\ndataset=sample\n\npython main.py --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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Programmatic Usage\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\n资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Local vLLM Deployment\n\nFor production environments or cost-sensitive deployments, HippoRAG supports self-hosted LLMs using vLLM.\n\n### Architecture\n\n```mermaid\ngraph TD\n A[HippoRAG Main Process] --> B[vLLM Server]\n A --> C[Local Embedding Model]\n B --> D[GPU 0-1]\n C --> D\n E[Indexing Pipeline] --> A\n F[QA Pipeline] --> A\n```\n\n### Starting vLLM Server\n\nLaunch the vLLM server with tensor parallelism for multi-GPU setups:\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资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Configuration Parameters\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `--llm_base_url` | vLLM server endpoint | `http://localhost:6578/v1` |\n| `--llm_name` | Model name (must match deployed model) | `meta-llama/Llama-3.1-8B-Instruct` |\n| `--embedding_name` | Local embedding model identifier | `nvidia/NV-Embed-v2` |\n\n### Running Main Process\n\nWith vLLM server running on GPUs 0-1, run the main process on separate GPUs:\n\n```bash\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\n\npython main.py --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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Azure OpenAI Deployment\n\nEnterprise deployments requiring Azure infrastructure can use Azure OpenAI endpoints.\n\n### Configuration Parameters\n\n| Parameter | CLI Argument | Description |\n|-----------|--------------|-------------|\n| `azure_endpoint` | `--azure_endpoint` | Azure OpenAI chat completions endpoint |\n| `azure_embedding_endpoint` | `--azure_embedding_endpoint` | Azure OpenAI embeddings endpoint |\n\n### Endpoint Format\n\n```python\nazure_endpoint = (\n \"https://[ENDPOINT_NAME].openai.azure.com/\"\n \"openai/deployments/gpt-4o-mini/chat/completions\"\n \"?api-version=2025-01-01-preview\"\n)\n\nazure_embedding_endpoint = (\n \"https://[ENDPOINT_NAME].openai.azure.com/\"\n \"openai/deployments/text-embedding-3-small/embeddings\"\n \"?api-version=2023-05-15\"\n)\n```\n\n资料来源：[demo_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.py)\n\n### Programmatic Usage\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 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\nhipporag.index(docs=docs)\n```\n\n资料来源：[demo_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.py)\n\n### CLI Usage\n\n```bash\npython main_azure.py \\\n --dataset sample \\\n --azure_endpoint \"https://[ENDPOINT].openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2025-01-01-preview\" \\\n --azure_embedding_endpoint \"https://[ENDPOINT].openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2023-05-15\" \\\n --save_dir outputs\n```\n\n资料来源：[main_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_azure.py)\n\n## Indexing Options\n\n### OpenIE Modes\n\nHippoRAG supports two Open Information Extraction (OpenIE) modes:\n\n| Mode | Description | Resource Usage |\n|------|-------------|----------------|\n| `online` | Uses OpenAI GPT for real-time extraction | API costs |\n| `offline` | Uses local vLLM batch processing | GPU compute |\n\n```bash\npython main.py --dataset $dataset --openie_mode offline\n```\n\n资料来源：[main.py:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n### Force Rebuild Options\n\n| Parameter | Description |\n|-----------|-------------|\n| `--force_index_from_scratch` | Ignores existing storage and rebuilds from scratch |\n| `--force_openie_from_scratch` | Ignores cached OpenIE results and recomputes |\n\n```bash\npython main_azure.py \\\n --force_index_from_scratch true \\\n --force_openie_from_scratch true\n```\n\n资料来源：[main_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_azure.py)\n\n## StandardRAG vs HippoRAG\n\nThe codebase provides two RAG implementations selectable via configuration:\n\n```python\n# Standard HippoRAG (default)\nhipporag = HippoRAG(global_config=config)\n\n# Alternative DPR-style implementation\nhipporag = StandardRAG(global_config=config)\n```\n\n资料来源：[main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py) and [main_dpr.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_dpr.py)\n\n## Installation Requirements\n\nAll deployment options require the HippoRAG package and its dependencies:\n\n```bash\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install hipporag\n```\n\nOr install from source:\n\n```bash\npip install -e .\n```\n\nCore dependencies include:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `torch` | 2.5.1 | Deep learning framework |\n| `transformers` | 4.45.2 | Model loading |\n| `vllm` | 0.6.6.post1 | Local inference |\n| `openai` | 1.91.1 | API client |\n| `litellm` | 1.73.1 | Unified LLM interface |\n| `gritlm` | 1.0.2 | Embedding models |\n| `networkx` | 3.4.2 | Graph operations |\n| `pydantic` | 2.10.4 | Configuration validation |\n\n资料来源：[setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n\n## Testing Deployments\n\n### OpenAI Test\n\n```bash\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Local vLLM Test\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\n# Start vLLM server\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# Run tests\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Azure Test\n\n```bash\npython tests_azure.py\n```\n\n资料来源：[tests_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_azure.py)\n\n## Deployment Decision Matrix\n\n| Criteria | OpenAI API | vLLM Local | Azure |\n|----------|------------|------------|-------|\n| Setup complexity | Low | High | Medium |\n| Cost | Pay-per-use | GPU infrastructure | Azure subscription |\n| Data privacy | Data leaves your environment | All data stays local | Configurable |\n| Latency | Network dependent | Local, optimized | Network dependent |\n| Model flexibility | Limited to API models | Any HuggingFace model | Limited to deployed models |\n| Recommended for | Development, prototyping | Production, research | Enterprise compliance |\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 项目说明书",
"目录",
"Installation and Setup",
"Overview",
"System Requirements",
"Installation Methods",
"Environment Variables",
"Set CUDA visible devices",
"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- **Installation and Setup**：importance `high`\n - source_paths: requirements.txt, setup.py, README.md\n- **Quick Start Guide**：importance `high`\n - source_paths: demo.py, demo_openai.py, src/hipporag/HippoRAG.py\n- **Configuration System**：importance `medium`\n - source_paths: src/hipporag/utils/config_utils.py, main.py\n- **HippoRAG Core Class**：importance `high`\n - source_paths: src/hipporag/HippoRAG.py, src/hipporag/StandardRAG.py\n- **Knowledge Graph and Retrieval**：importance `high`\n - source_paths: src/hipporag/utils/embed_utils.py, src/hipporag/utils/qa_utils.py, src/hipporag/rerank.py\n- **Embedding Store and Management**：importance `medium`\n - source_paths: src/hipporag/embedding_store.py, src/hipporag/utils/embed_utils.py\n- **LLM Integrations**：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\n- **Embedding Models**：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\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:41:44 UTC\n\n## 目录\n\n- [Installation and Setup](#page-1)\n- [Quick Start Guide](#page-2)\n- [Configuration System](#page-3)\n- [HippoRAG Core Class](#page-4)\n- [Knowledge Graph and Retrieval](#page-5)\n- [Embedding Store and Management](#page-6)\n- [LLM Integrations](#page-7)\n- [Embedding Models](#page-8)\n- [Open Information Extraction (OpenIE)](#page-9)\n- [Deployment Options](#page-10)\n\n\n\n## Installation and Setup\n\n### 相关页面\n\n相关主题：[Configuration System](#page-3), [Deployment Options](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n- [test_transformers.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/test_transformers.py)\n- [CONTRIBUTING.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/CONTRIBUTING.md)\n \n\n# Installation and Setup\n\n## Overview\n\nHippoRAG is a graph-based Retrieval-Augmented Generation (RAG) framework designed to enable Large Language Models (LLMs) to identify and leverage connections within knowledge bases for improved retrieval and question answering. The installation process configures the necessary dependencies, environment variables, and model configurations to run HippoRAG in either cloud (OpenAI) or local (vLLM) deployment modes.\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## System Requirements\n\n### Python Version\n\n| Requirement | Version |\n|-------------|---------|\n| Python | >= 3.10 |\n\nThe package explicitly requires Python 3.10 or higher as specified in the `setup.py` configuration.\n\n资料来源：[setup.py:16](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L16)\n\n### Hardware Requirements\n\n| Component | Requirement |\n|-----------|-------------|\n| GPU | CUDA-compatible GPU(s) recommended |\n| GPU Memory | Varies based on model size (see deployment sections) |\n\nFor local deployment with vLLM, the framework supports tensor parallelism across multiple GPUs. The README recommends reserving enough memory for embedding models when deploying LLM servers.\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Installation Methods\n\n### Method 1: pip Installation (Recommended)\n\n```sh\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install hipporag\n```\n\nThis method installs HippoRAG version 2.0.0-alpha.4 along with all core dependencies from PyPI.\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Method 2: Source Installation (For Development)\n\n```sh\ngit clone https://github.com/OSU-NLP-Group/HippoRAG.git\ncd HippoRAG\npip install -e .\n```\n\nClone the repository and install in editable mode to work with the latest source code.\n\n资料来源：[CONTRIBUTING.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/CONTRIBUTING.md)\n\n## Environment Variables\n\nProper configuration of environment variables is essential for HippoRAG to function correctly. These variables control GPU allocation, model caching, and API access.\n\n### Required Environment Variables\n\n| Variable | Description | Example |\n|----------|-------------|---------|\n| `CUDA_VISIBLE_DEVICES` | Comma-separated list of GPU device IDs | `0,1,2,3` |\n| `HF_HOME` | Path to Hugging Face cache directory | `/path/to/huggingface/home` |\n| `OPENAI_API_KEY` | API key for OpenAI models (cloud mode only) | `sk-...` |\n\n### Setting Environment Variables\n\n```sh\n# Set CUDA visible devices\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\n\n# Set Hugging Face cache location\nexport HF_HOME=\n\n# Set OpenAI API key (required for cloud deployment)\nexport OPENAI_API_KEY=\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Core Dependencies\n\nHippoRAG depends on a comprehensive set of libraries for LLM inference, embedding models, graph processing, and data handling.\n\n### Dependency Overview\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| torch | 2.5.1 | PyTorch deep learning framework |\n| transformers | 4.45.2 | Model architectures and tokenizers |\n| vllm | 0.6.6.post1 | High-throughput LLM inference |\n| openai | 1.91.1 | OpenAI API client |\n| litellm | 1.73.1 | Unified LLM interface |\n| gritlm | 1.0.2 | Embedding model |\n| networkx | 3.4.2 | Graph data structures |\n| python_igraph | 0.11.8 | Graph algorithms |\n| tiktoken | 0.7.0 | Tokenization |\n| pydantic | 2.10.4 | Data validation |\n| tenacity | 8.5.0 | Retry logic |\n| einops | (latest) | Tensor operations |\n| tqdm | (latest) | Progress bars |\n| boto3 | (latest) | AWS S3 integration |\n\n资料来源：[setup.py:17-32](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py#L17-L32), [requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n\n### Additional Dependencies\n\nThe `requirements.txt` file includes additional packages not pinned to specific versions:\n\n| Package | Purpose |\n|---------|---------|\n| nest_asyncio | Asynchronous operations |\n| numpy | Numerical computing |\n| scipy | Scientific computing |\n\n资料来源：[requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n\n## Configuration\n\nHippoRAG uses a Pydantic-based configuration system defined in `BaseConfig` within `config_utils.py`. This configuration controls all aspects of indexing, retrieval, and QA.\n\n### Configuration Parameters\n\n#### Embedding Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| embedding_model_name | nvidia/NV-Embed-v2 | Name of the embedding model |\n| embedding_batch_size | 16 | Batch size for embedding encoding |\n| embedding_return_as_normalized | True | Whether to normalize embeddings |\n| embedding_max_seq_len | 2048 | Maximum sequence length for embeddings |\n| embedding_model_dtype | auto | Data type for local embedding models |\n\n#### Retrieval Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| retrieval_top_k | 200 | Number of documents to retrieve |\n| linking_top_k | 5 | Number of linked nodes per retrieval step |\n| damping | 0.5 | Damping factor for PPR algorithm |\n| passage_node_weight | 0.05 | Weight modifier for passage nodes in PPR |\n\n#### QA Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| max_qa_steps | 1 | Maximum steps for interleaved retrieval and reasoning |\n| qa_top_k | 5 | Top k documents fed to QA model |\n\n#### Graph Construction Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| synonymy_edge_topk | 2047 | K for KNN retrieval in synonymy edge building |\n| synonymy_edge_sim_threshold | 0.8 | Similarity threshold for synonymy nodes |\n| is_directed_graph | False | Whether the graph is directed |\n| graph_type | facts_and_sim_passage_node_unidirectional | Type of graph structure |\n\n#### Information Extraction Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| information_extraction_model_name | openie_openai_gpt | OpenIE model class name |\n| openie_mode | online | Mode: \"online\" or \"offline\" |\n\n#### Preprocessing Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| text_preprocessor_class_name | TextPreprocessor | Preprocessor class name |\n| preprocess_encoder_name | gpt-4o | Encoder for preprocessing |\n| preprocess_chunk_overlap_token_size | 128 | Overlap tokens between chunks |\n| preprocess_chunk_max_token_size | None | Max tokens per chunk (None = whole doc) |\n| preprocess_chunk_func | by_token | Chunking function type |\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## Deployment Modes\n\nHippoRAG supports two primary deployment modes for LLM inference.\n\n```mermaid\ngraph TD\n A[HippoRAG Deployment] --> B[Cloud Mode]\n A --> C[Local Mode]\n \n B --> B1[OpenAI API]\n B --> B2[OpenAI Compatible API]\n \n C --> C1[vLLM Server]\n C --> C1b[Local Embedding Model]\n \n B1 --> D[Requires OPENAI_API_KEY]\n B2 --> E[Custom LLM Base URL]\n C1 --> F[Multi-GPU Support]\n```\n\n### Cloud Mode (OpenAI)\n\nCloud mode uses OpenAI's API for both LLM and embedding inference.\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\n#### OpenAI Compatible Embeddings\n\nFor OpenAI-compatible embedding endpoints:\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资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Local Mode (vLLM)\n\nLocal mode deploys LLM servers using vLLM for offline inference with GPU acceleration.\n\n#### Step 1: Start vLLM Server\n\n```sh\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#### Step 2: Run HippoRAG with Different GPUs\n\n```sh\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\npython main.py --dataset sample --llm_base_url http://localhost:6578/v1\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Quick Start Workflow\n\n```mermaid\ngraph LR\n A[Install HippoRAG] --> B[Configure Environment]\n B --> C[Set Environment Variables]\n C --> D[Initialize HippoRAG]\n D --> E[index Documents]\n E --> F[RAG QA Queries]\n```\n\n### Complete Example\n\n```python\nfrom hipporag import HippoRAG\n\n# Define documents\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# Initialize 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# Index documents\nhipporag.index(docs)\n\n# Define queries and gold standard answers\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\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 [\"Montebello is a part of Rockland County.\"]\n]\n\nanswers = [\n [\"Politician\"],\n [\"By going to the ball.\"],\n [\"Rockland County\"]\n]\n\n# Run RAG QA\nresults = 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## Testing Your Installation\n\n### OpenAI Test\n\nRun this test to verify cloud mode functionality:\n\n```sh\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n### Local Test\n\nRun this test to verify local vLLM mode:\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\n# Start vLLM server\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# Run local test\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Troubleshooting\n\n### Out of Memory (OOM) Errors\n\nIf you encounter OOM errors during local deployment:\n\n1. Reduce `gpu-memory-utilization` parameter in vLLM\n2. Reduce `max_model_len` in vLLM server\n3. Adjust `CUDA_VISIBLE_DEVICES` to use more GPUs\n4. Reduce `embedding_batch_size` in configuration\n\n### Environment Variable Issues\n\nEnsure all required environment variables are set before running HippoRAG:\n\n```sh\n# Verify environment variables are set\necho $CUDA_VISIBLE_DEVICES\necho $HF_HOME\necho $OPENAI_API_KEY\n```\n\n### Conda Environment\n\nAlways activate the correct conda environment before running commands:\n\n```sh\nconda activate hipporag\n```\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Reproducing Experiments\n\nTo reproduce the paper's experiments:\n\n1. Clone the repository and install dependencies\n2. Download datasets from [HuggingFace](https://huggingface.co/datasets/osunlp/HippoRAG_v2) or use provided samples in `reproduce/dataset`\n3. Set required environment variables\n4. Run the main script with appropriate parameters:\n\n```sh\n# OpenAI model\npython main.py \\\n --dataset sample \\\n --llm_base_url https://api.openai.com/v1 \\\n --llm_name gpt-4o-mini \\\n --embedding_name nvidia/NV-Embed-v2\n\n# Local vLLM model\npython main.py \\\n --dataset sample \\\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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md), [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n---\n\n\n\n## Quick Start Guide\n\n### 相关页面\n\n相关主题：[Installation and Setup](#page-1), [HippoRAG Core Class](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [demo_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.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- [src/hipporag/HippoRAG.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/HippoRAG.py)\n- [requirements.txt](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/requirements.txt)\n \n\n# Quick Start Guide\n\nThis guide provides a comprehensive walkthrough for setting up and running HippoRAG, enabling you to quickly leverage neurobiologically inspired long-term memory capabilities for Large Language Models.\n\n## Prerequisites\n\nBefore beginning, ensure your environment meets the following requirements:\n\n| Requirement | Specification |\n|------------|---------------|\n| Python | >= 3.10 |\n| CUDA GPUs | Required for local embedding model inference |\n| HuggingFace Home | Configured via `HF_HOME` environment variable |\n| API Keys | OpenAI API key (if using OpenAI models) |\n\n### Environment Setup\n\n```sh\n# Create conda environment\nconda create -n hipporag python=3.10\nconda activate hipporag\n\n# Install HippoRAG\npip install hipporag\n\n# Configure environment variables\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=\n```\n\n资料来源：[README.md:150-165]()\n\n## Core Usage Patterns\n\nHippoRAG supports three primary deployment configurations. The initialization workflow follows this pattern:\n\n```mermaid\ngraph TD\n A[Initialize HippoRAG] --> B{Select LLM Backend}\n B -->|OpenAI| C[Set llm_model_name + llm_base_url]\n B -->|vLLM| D[Set llm_model_name + llm_base_url]\n B -->|Azure| E[Set azure_endpoint]\n A --> F{Select Embedding Backend}\n F -->|HuggingFace| G[Set embedding_model_name]\n F -->|Custom| H[Set embedding_base_url]\n```\n\n资料来源：[demo_azure.py:1-30]()\n\n### Pattern 1: OpenAI Models\n\nThe simplest configuration uses OpenAI for both LLM inference and embeddings:\n\n```python\nfrom hipporag import HippoRAG\n\n# Configuration\nsave_dir = 'outputs'\nllm_model_name = 'gpt-4o-mini'\nembedding_model_name = 'nvidia/NV-Embed-v2'\n\n# Initialize HippoRAG instance\nhipporag = HippoRAG(\n save_dir=save_dir, \n llm_model_name=llm_model_name,\n embedding_model_name=embedding_model_name\n)\n```\n\n资料来源：[README.md:175-195]()\n\n### Pattern 2: OpenAI Compatible Embeddings\n\nFor custom LLM endpoints that follow OpenAI's API format:\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资料来源：[README.md:210-220]()\n\n### Pattern 3: Azure OpenAI Integration\n\nFor Azure-hosted models:\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资料来源：[demo_azure.py:10-15]()\n\n## Indexing Documents\n\nThe indexing process converts raw documents into HippoRAG's knowledge graph structure:\n\n```mermaid\ngraph LR\n A[Raw Documents] --> B[Chunking]\n B --> C[OpenIE Extraction]\n C --> D[Embedding Generation]\n D --> E[Graph Construction]\n E --> F[Knowledge Graph Index]\n```\n\n### Input Data Format\n\nDocuments should be provided as a list of strings:\n\n```python\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]\n```\n\n### Execute Indexing\n\n```python\nhipporag.index(docs=docs)\n```\n\n资料来源：[demo_azure.py:18-45]()\n\n## Retrieval and Question Answering\n\nThe `rag_qa` method performs retrieval-augmented question answering:\n\n```mermaid\ngraph TD\n A[Query Input] --> B[Retrieval]\n B --> C[Personalized PageRank]\n C --> D[Document Selection]\n D --> E[QA Generation]\n E --> F[Final Answer]\n \n C -.->|links documents| G[Knowledge Graph]\n G -.->|context| D\n```\n\n### Complete QA Example\n\n```python\n# Prepare queries and evaluation data\nqueries = [\n \"What is George Rankin's occupation?\",\n \"How did Cinderella reach her happy ending?\"\n]\n\nanswers = [\n [\"Politician\"],\n [\"By going to the ball.\"]\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]\n\n# Execute RAG QA\nresults = hipporag.rag_qa(\n queries=queries, \n gold_docs=gold_docs,\n gold_answers=answers\n)\n\nprint(results)\n```\n\n资料来源：[README.md:195-215]()\n\n## Local Deployment with vLLM\n\nFor running LLMs locally, HippoRAG supports vLLM server integration:\n\n### Step 1: Start vLLM Server\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0,1\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nconda activate hipporag\n\n# Adjust gpu-memory-utilization and max_model_len based on your GPU memory\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:225-240]()\n\n### Step 2: Initialize HippoRAG with vLLM\n\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 embedding_model_name='nvidia/NV-Embed-v2'\n)\n```\n\n## Reproducing Experiments\n\nFor reproducing published experiments, follow the structured workflow:\n\n### Dataset Structure\n\n| File Type | Naming Convention | Purpose |\n|-----------|-------------------|---------|\n| Corpus | `{dataset}_corpus.json` | Document collection |\n| Queries | `{dataset}.json` | Questions with answers |\n| Output | `outputs/{dataset}/` | Index and results |\n\n### Corpus JSON Format\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:100-125]()\n\n### Running Experiments\n\n```sh\n# Set environment variables\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\nexport OPENAI_API_KEY=\nconda activate hipporag\n\n# Run with OpenAI model\ndataset=sample\npython main.py --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资料来源：[main.py:1-35]()\n\n## Testing Your Installation\n\n### OpenAI Test\n\nVerify installation with minimal OpenAI API cost:\n\n```sh\nexport OPENAI_API_KEY= \nconda activate hipporag\npython tests_openai.py\n```\n\n### Local Test with vLLM\n\nTest with a locally deployed model:\n\n```sh\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\nconda activate hipporag\n\n# Start vLLM server with smaller model\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# Run test\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:250-280]()\n\n## Configuration Parameters\n\n### Core Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `save_dir` | `outputs` | Directory for saving all related information |\n| `llm_model_name` | - | LLM model identifier |\n| `llm_base_url` | - | Base URL for LLM API endpoint |\n| `embedding_model_name` | `nvidia/NV-Embed-v2` | Embedding model identifier |\n| `embedding_batch_size` | `16` | Batch size for embedding model |\n\n资料来源：[src/hipporag/utils/config_utils.py:50-80]()\n\n### Retrieval Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `retrieval_top_k` | `200` | Number of documents to retrieve initially |\n| `linking_top_k` | `5` | Number of linked nodes at each retrieval step |\n| `qa_top_k` | `5` | Number of documents fed to QA model |\n| `max_qa_steps` | `1` | Maximum interleaved retrieval-reasoning steps |\n| `damping` | `0.5` | Damping factor for Personalized PageRank |\n\n资料来源：[src/hipporag/utils/config_utils.py:30-50]()\n\n### Graph Construction Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `synonymy_edge_topk` | `2047` | K for KNN retrieval in synonymy edge building |\n| `synonymy_edge_sim_threshold` | `0.8` | Similarity threshold for synonymy nodes |\n| `graph_type` | `facts_and_sim_passage_node_unidirectional` | Type of graph structure to construct |\n| `is_directed_graph` | `False` | Whether to build a directed graph |\n\n资料来源：[src/hipporag/utils/config_utils.py:80-110]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| CUDA OOM errors | Reduce `gpu-memory-utilization` or `max_model_len` in vLLM; reduce `embedding_batch_size` |\n| Connection errors | Verify API endpoint URLs and network connectivity |\n| Index loading failures | Check that `save_dir` contains valid index files |\n\n### Environment Validation\n\nAlways verify your setup before running experiments:\n\n```sh\n# Verify CUDA availability\npython -c \"import torch; print(torch.cuda.is_available())\"\n\n# Verify package installation\npip list | grep hipporag\n```\n\n## Next Steps\n\n- Explore the [Code Structure documentation](README.md#code-structure) for deep-dive into modules\n- Review experiment reproducibility guidelines in `main.py`\n- Access pre-processed datasets from the [HuggingFace dataset page](https://huggingface.co/datasets/osunlp/HippoRAG_v2)\n\n---\n\n\n\n## Configuration System\n\n### 相关页面\n\n相关主题：[Installation and Setup](#page-1), [HippoRAG Core Class](#page-4)\n\n\nRelated Source Files
\n\nThe following source files were used to generate this documentation page:\n\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\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- [tests_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)\n- [test_transformers.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/test_transformers.py)\n \n\n# Configuration System\n\nHippoRAG provides a comprehensive configuration system built on Pydantic's data validation framework. The configuration system enables fine-grained control over all aspects of the indexing, retrieval, and QA pipeline while maintaining type safety and default values for common use cases.\n\n## Architecture Overview\n\nThe configuration system is centered around the `BaseConfig` class defined in `config_utils.py`. This class uses Pydantic's `BaseModel` with `Field` definitions to provide structured configuration with metadata and validation.\n\n```mermaid\ngraph TD\n A[BaseConfig] --> B[OpenIE Configuration]\n A --> C[Embedding Configuration]\n A --> D[Graph Construction Configuration]\n A --> E[Retrieval Configuration]\n A --> F[QA Configuration]\n A --> G[Save/Directory Configuration]\n A --> H[Dataset Configuration]\n \n I[main.py] --> A\n J[HippoRAG class] --> A\n K[StandardRAG class] --> A\n```\n\nSource: [src/hipporag/utils/config_utils.py:1-100]()\n\n## Core Configuration Class\n\n### BaseConfig\n\nThe `BaseConfig` class serves as the single source of truth for all pipeline parameters. It inherits from Pydantic's `BaseModel` and provides automatic validation, serialization, and documentation through field metadata.\n\n```python\nfrom hipporag.utils.config_utils import BaseConfig\n\nglobal_config = BaseConfig(\n openie_mode='openai_gpt',\n information_extraction_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\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)\n```\n\nSource: [main.py:20-35]()\n\n## Configuration Categories\n\n### OpenIE (Open Information Extraction) Configuration\n\nControls the information extraction module that identifies facts and entities from passages.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `openie_mode` | `Literal[\"openai_gpt\", \"vllm_offline\", \"Transformers-offline\"]` | `\"openai_gpt\"` | The mode for information extraction model |\n| `information_extraction_model_name` | `str` | `\"gpt-4o-mini\"` | Model name for information extraction |\n\nThe `openie_mode` parameter supports three execution modes:\n- **`openai_gpt`**: Uses OpenAI's GPT models for extraction via API\n- **`vllm_offline`**: Uses locally deployed LLMs through vLLM server\n- **`Transformers-offline`**: Uses HuggingFace Transformers models directly\n\nSource: [src/hipporag/utils/config_utils.py:config_fields]()\n\n### Embedding Model Configuration\n\nManages embedding generation for passages and queries.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `embedding_model_name` | `str` | `\"nvidia/NV-Embed-v2\"` | Name of the embedding model |\n| `embedding_batch_size` | `int` | `16` | Batch size for embedding generation |\n| `embedding_return_as_normalized` | `bool` | `True` | Whether to normalize embeddings |\n| `embedding_max_seq_len` | `int` | `2048` | Maximum sequence length for embedding model |\n| `embedding_model_dtype` | `Literal[\"float16\", \"float32\", \"bfloat16\", \"auto\"]` | `\"auto\"` | Data type for local embedding model |\n| `embedding_base_url` | `Optional[str]` | `None` | Base URL for OpenAI-compatible embedding endpoints |\n\nSource: [src/hipporag/utils/config_utils.py:embedding_batch_size-def]()\n\n### Graph Construction Configuration\n\nControls the knowledge graph construction process that forms the backbone of HippoRAG's memory system.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `synonymy_edge_topk` | `int` | `2047` | K value for KNN retrieval in building synonymy edges |\n| `synonymy_edge_query_batch_size` | `int` | `1000` | Batch size for query embeddings during KNN retrieval |\n| `synonymy_edge_key_batch_size` | `int` | `10000` | Batch size for key embeddings during KNN retrieval |\n| `synonymy_edge_sim_threshold` | `float` | `0.8` | Similarity threshold for including candidate synonymy nodes |\n| `is_directed_graph` | `bool` | `False` | Whether the constructed graph is directed or undirected |\n| `graph_type` | `str` | `\"facts_and_sim_passage_node_unidirectional\"` | Type of graph structure to build |\n\nSupported `graph_type` values include:\n- `facts_and_sim_passage_node_unidirectional` - Passages connected via facts with similarity edges\n- `facts_and_sim_passage_node_bidirectional` - Bidirectional passage connections\n- `facts_only` - Only fact-based connections\n- `sim_passage_node` - Only passage similarity connections\n\nSource: [src/hipporag/utils/config_utils.py:synonymy_edge_topk-def]()\n\n### Retrieval Configuration\n\nParameters governing the retrieval and linking process using Personalized PageRank (PPR).\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `linking_top_k` | `int` | `5` | Number of linked nodes at each retrieval step |\n| `retrieval_top_k` | `int` | `200` | Number of documents to retrieve at each step |\n| `damping` | `float` | `0.5` | Damping factor for PPR algorithm |\n\nThe `damping` parameter controls the probability of following graph edges during the random walk in PPR. A higher value (closer to 1.0) results in more exploration, while lower values favor exploitation of high-probability paths.\n\nSource: [src/hipporag/utils/config_utils.py:linking_top_k-def](), [main.py:28]()\n\n### QA (Question Answering) Configuration\n\nControls the iterative QA process that interleaves retrieval with reasoning.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `max_qa_steps` | `int` | `1` | Maximum steps for interleaved retrieval and reasoning |\n| `qa_top_k` | `int` | `5` | Number of top documents fed to the QA model |\n\nThe `max_qa_steps` parameter enables multi-step reasoning where the system can retrieve additional documents based on intermediate reasoning results before producing the final answer.\n\nSource: [src/hipporag/utils/config_utils.py:max_qa_steps-def](), [main.py:27]()\n\n### LLM Configuration\n\nManages the language model used for QA and information extraction.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `llm_model_name` | `str` | `\"gpt-4o-mini\"` | Name of the LLM |\n| `llm_base_url` | `Optional[str]` | `None` | Base URL for OpenAI-compatible LLM endpoints |\n| `max_new_tokens` | `Optional[int]` | `None` | Maximum new tokens for generation |\n\nSource: [src/hipporag/utils/config_utils.py:llm_model_name-def]()\n\n### Save and Directory Configuration\n\nControls output persistence and directory structure.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `save_dir` | `str` | `\"outputs\"` | Top-level directory for saving all related information |\n| `corpus_len` | `int` | Required | Length of the corpus being processed |\n\nThe `save_dir` parameter specifies where HippoRAG objects, intermediate results, and evaluation outputs are stored. When running with specific datasets, the default saves to a dataset-customized output directory under `save_dir`.\n\nSource: [src/hipporag/utils/config_utils.py:save_dir-def](), [main.py:32]()\n\n## Configuration Workflow\n\n```mermaid\ngraph LR\n A[Define BaseConfig] --> B[Initialize HippoRAG]\n B --> C[Index Documents]\n C --> D[Run RAG QA]\n D --> E[Results Saved to save_dir]\n \n F[Modify Config] -->|Update| B\n G[New Documents] -->|Index| C\n```\n\n### Initialization Example\n\n```python\nfrom hipporag.utils.config_utils import BaseConfig\nfrom hipporag import HippoRAG\n\nconfig = BaseConfig(\n openie_mode='openai_gpt',\n information_extraction_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\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 max_new_tokens=None,\n corpus_len=len(corpus),\n)\n\nhipporag = HippoRAG(global_config=config)\n```\n\nSource: [main.py:19-38]()\n\n## Configuration for Different Execution Modes\n\n### OpenAI API Mode\n\n```python\nconfig = BaseConfig(\n openie_mode='openai_gpt',\n information_extraction_model_name='gpt-4o-mini',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\n)\n```\n\nSource: [main.py:20-26]()\n\n### Local vLLM Deployment Mode\n\n```python\nconfig = BaseConfig(\n openie_mode='vllm_offline',\n information_extraction_model_name='meta-llama/Llama-3.1-8B-Instruct',\n llm_model_name='meta-llama/Llama-3.3-70B-Instruct',\n llm_base_url='http://localhost:8000/v1',\n embedding_model_name='nvidia/NV-Embed-v2',\n)\n```\n\nSource: [README.md:vllm_example]()\n\n### Transformers Offline Mode\n\n```python\nconfig = BaseConfig(\n openie_mode='Transformers-offline',\n information_extraction_model_name='Transformers/Qwen/Qwen2.5-7B-Instruct',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\n)\n```\n\nSource: [test_transformers.py:16-20]()\n\n## Testing with Configuration\n\nThe test suite demonstrates configuration usage across different scenarios:\n\n```python\n# tests_openai.py - Basic indexing and QA\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# tests_openai.py - Document deletion\nhipporag.delete(docs_to_delete)\n\n# test_transformers.py - Transformers offline mode\nhipporag = HippoRAG(\n global_config=global_config,\n save_dir=save_dir,\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2',\n)\n```\n\nSource: [tests_openai.py:test_structure](), [test_transformers.py:16-25]()\n\n## Package Dependencies\n\nThe configuration system depends on the following packages specified in `setup.py`:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `torch` | `2.5.1` | PyTorch backend for models |\n| `transformers` | `4.45.2` | HuggingFace Transformers |\n| `pydantic` | `2.10.4` | Data validation and settings |\n| `vllm` | `0.6.6.post1` | LLM inference server |\n| `openai` | `1.91.1` | OpenAI API client |\n| `litellm` | `1.73.1` | Unified LLM interface |\n| `gritlm` | `1.0.2` | GritLM embedding model |\n| `networkx` | `3.4.2` | Graph operations |\n| `python_igraph` | `0.11.8` | Graph algorithms |\n| `tiktoken` | `0.7.0` | Tokenization |\n| `tenacity` | `8.5.0` | Retry logic |\n\nSource: [setup.py:14-27]()\n\n## Best Practices\n\n1. **Use environment variables** for sensitive configuration like API keys:\n ```bash\n export OPENAI_API_KEY=\n export HF_HOME=\n ```\n\n2. **Set GPU devices** before initialization:\n ```bash\n export CUDA_VISIBLE_DEVICES=0,1,2,3\n ```\n\n3. **Adjust batch sizes** based on available GPU memory when using local models\n\n4. **Configure damping factor** carefully for retrieval - higher values (0.7-0.85) work better for complex multi-hop questions\n\n5. **Set corpus_len** correctly to enable proper progress tracking and memory management\n\n---\n\n\n\n## HippoRAG Core Class\n\n### 相关页面\n\n相关主题：[Knowledge Graph and Retrieval](#page-5), [Embedding Models](#page-8)\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- [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- [main_dpr.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_dpr.py)\n- [tests_openai.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_openai.py)\n \n\n# HippoRAG Core Class\n\n## Overview\n\nHippoRAG is a neurobiologically inspired graph-based Retrieval-Augmented Generation (RAG) framework designed to enable Large Language Models (LLMs) to identify and leverage connections within knowledge for improved retrieval and question answering. The project implements two primary RAG classes: `HippoRAG` (neurobiologically inspired with Personal Knowledge Graph) and `StandardRAG` (traditional DPR-based approach).\n\n资料来源：[setup.py:8-9]()\n\n## Architecture Overview\n\n```mermaid\ngraph TB\n subgraph \"Input Layer\"\n Docs[Documents/Passages]\n Queries[User Queries]\n end\n \n subgraph \"HippoRAG Core\"\n Index[Indexing Pipeline]\n Retrieve[Retrieval Pipeline]\n QA[Question Answering]\n end\n \n subgraph \"Knowledge Graph Construction\"\n OpenIE[OpenIE Information Extraction]\n Embed[Embedding Model]\n GraphBuild[Graph Building]\n end\n \n subgraph \"Backend Services\"\n LLM[LLM Inference]\n EmbedModel[Embedding Service]\n end\n \n Docs --> Index\n Index --> OpenIE\n Index --> Embed\n OpenIE --> GraphBuild\n Embed --> GraphBuild\n GraphBuild --> KG[Knowledge Graph]\n \n Queries --> Retrieve\n Retrieve --> KG\n KG --> QA\n QA --> LLM\n Retrieve --> EmbedModel\n```\n\n## Core Classes\n\n### HippoRAG Class\n\nThe `HippoRAG` class is the main entry point for the neurobiologically inspired RAG system. It extends a base RAG implementation with Personal Knowledge Graph (PKG) capabilities.\n\n**Initialization Parameters**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `save_dir` | `str` | Required | Directory to save all related information |\n| `llm_model_name` | `str` | Required | LLM model identifier (e.g., `gpt-4o-mini`) |\n| `embedding_model_name` | `str` | Required | Embedding model name (e.g., `nvidia/NV-Embed-v2`) |\n| `global_config` | `BaseConfig` | `None` | Full configuration object |\n| `llm_base_url` | `str` | `None` | Custom LLM API endpoint for OpenAI-compatible models |\n| `embedding_base_url` | `str` | `None` | Custom embedding API endpoint |\n| `azure_endpoint` | `str` | `None` | Azure OpenAI endpoint for LLM |\n| `azure_embedding_endpoint` | `str` | `None` | Azure OpenAI endpoint for embeddings |\n\n资料来源：[main.py:19-28]()\n\n**Basic Usage Pattern**\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# Index documents\nhipporag.index(docs=documents_list)\n\n# Retrieve and answer queries\nresults = hipporag.rag_qa(\n queries=query_list,\n gold_docs=expected_documents,\n gold_answers=expected_answers\n)\n```\n\n### StandardRAG Class\n\nThe `StandardRAG` class provides traditional Dense Passage Retrieval (DPR) based RAG without the Personal Knowledge Graph components. This is useful for baseline comparisons.\n\n资料来源：[main_dpr.py:19]()\n\n## Configuration System\n\n### BaseConfig Parameters\n\nThe `BaseConfig` class (defined in `src/hipporag/utils/config_utils.py`) provides comprehensive configuration options:\n\n**OpenIE Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `openie_mode` | `str` | Required | OpenIE mode: `OpenAI`, `vllm-offline`, or `Transformers-offline` |\n| `information_extraction_model_name` | `str` | `None` | Model for offline OpenIE (e.g., `Qwen/Qwen2.5-7B-Instruct`) |\n\n**Embedding Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `embedding_batch_size` | `int` | `16` | Batch size for embedding model inference |\n| `embedding_return_as_normalized` | `bool` | `True` | Whether to normalize embeddings |\n| `embedding_max_seq_len` | `int` | `2048` | Maximum sequence length for embedding |\n| `embedding_model_dtype` | `str` | `\"auto\"` | Data type: `float16`, `float32`, `bfloat16`, or `auto` |\n\n**Graph Construction Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `synonymy_edge_topk` | `int` | `2047` | K value for KNN retrieval in synonymy edge construction |\n| `synonymy_edge_query_batch_size` | `int` | `1000` | Batch size for query embeddings |\n| `synonymy_edge_key_batch_size` | `int` | `10000` | Batch size for key embeddings |\n| `synonymy_edge_sim_threshold` | `float` | `0.8` | Similarity threshold for synonymy edges |\n| `is_directed_graph` | `bool` | `False` | Whether the graph is directed |\n\n**Retrieval Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `retrieval_top_k` | `int` | `200` | Number of documents to retrieve initially |\n| `linking_top_k` | `int` | `5` | Number of linked nodes at each retrieval step |\n| `damping` | `float` | `0.5` | Damping factor for Personalized PageRank |\n\n**QA Configuration**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `max_qa_steps` | `int` | `1` | Maximum interleaved retrieval and reasoning steps |\n| `qa_top_k` | `int` | `5` | Top k documents fed to QA model |\n\n资料来源：[src/hipporag/utils/config_utils.py:1-80]()\n\n## Core Methods\n\n### Indexing Pipeline\n\n```mermaid\ngraph LR\n A[Documents] --> B[Passage Embedding]\n B --> C[OpenIE Extraction]\n C --> D[Fact Node Creation]\n D --> E[Similarity Edge Building]\n E --> F[Knowledge Graph]\n```\n\n**Method Signature**\n\n```python\ndef index(self, docs: List[str], **kwargs) -> None\n```\n\nThe indexing process:\n1. Embeds passages using the configured embedding model\n2. Runs OpenIE to extract factual triples from each passage\n3. Constructs fact nodes and passage nodes in the knowledge graph\n4. Builds synonymy edges based on embedding similarity\n5. Persists the graph structure to `save_dir`\n\n### RAG QA Pipeline\n\n```mermaid\ngraph TD\n Q[Query] --> EP[Embedding]\n EP --> PPR[Personalized PageRank]\n PPR --> LN[Linked Nodes]\n LN --> LLM[LLM Reasoning]\n LLM -->|Iteration| Check{More Steps?}\n Check -->|Yes| EP\n Check -->|No| Final[Final Answer]\n```\n\n**Method Signature**\n\n```python\ndef rag_qa(\n self,\n queries: List[str],\n gold_docs: Optional[List[List[str]]] = None,\n gold_answers: Optional[List[List[str]]] = None,\n **kwargs\n) -> Dict\n```\n\n**Parameters**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `queries` | `List[str]` | Yes | List of questions to answer |\n| `gold_docs` | `List[List[str]]` | No | Ground truth documents for evaluation |\n| `gold_answers` | `List[List[str]]` | No | Ground truth answers for evaluation |\n\n**Returns**\n\nA dictionary containing evaluation metrics and retrieved results.\n\n### Document Deletion\n\n```python\ndef delete(self, docs_to_delete: List[str]) -> None\n```\n\nRemoves specified documents from the knowledge graph and updates persistence.\n\n## Supported Backend Models\n\n### LLM Backends\n\n| Backend | Configuration | Example Model |\n|---------|---------------|---------------|\n| OpenAI | `llm_model_name` | `gpt-4o-mini` |\n| Azure OpenAI | `azure_endpoint` | Azure deployment URL |\n| vLLM (Local) | `llm_base_url` + vLLM server | `meta-llama/Llama-3.1-8B-Instruct` |\n| OpenAI-Compatible | `llm_model_name` + `llm_base_url` | Custom endpoint |\n\n资料来源：[README.md:80-95]()\n\n### Embedding Models\n\n| Model Type | Configuration | Notes |\n|------------|---------------|-------|\n| NV-Embed-v2 | `embedding_model_name='nvidia/NV-Embed-v2'` | Recommended |\n| GritLM | `embedding_model_name='GritLM'` | Supported |\n| Contriever | `embedding_model_name='Contriever'` | Supported |\n| Azure Embeddings | `azure_embedding_endpoint` | Via Azure OpenAI |\n| Custom OpenAI-Compatible | `embedding_base_url` | Any compatible endpoint |\n\n## OpenIE Modes\n\nHippoRAG supports three OpenIE (Open Information Extraction) modes:\n\n| Mode | Description | Use Case |\n|------|-------------|----------|\n| `OpenAI` | Uses OpenAI GPT models for extraction | Cloud-based, high quality |\n| `vllm-offline` | Uses locally deployed vLLM models | GPU-equipped servers |\n| `Transformers-offline` | Uses HuggingFace Transformers | CPU or limited GPU |\n\n资料来源：[test_transformers.py:20-22]()\n\n## Workflow Example\n\n```python\nfrom hipporag import HippoRAG\n\n# Initialize\nhipporag = HippoRAG(\n save_dir='outputs',\n llm_model_name='gpt-4o-mini',\n embedding_model_name='nvidia/NV-Embed-v2'\n)\n\n# Prepare data\ndocs = [\n \"Oliver Badman is a politician.\",\n \"George Rankin is a politician.\",\n \"Cinderella attended the royal ball.\"\n]\n\n# Index\nhipporag.index(docs=docs)\n\n# Query\nqueries = [\"What is George Rankin's occupation?\"]\nanswers = [[\"Politician\"]]\ngold_docs = [[\"George Rankin is a politician.\"]]\n\n# Retrieve and evaluate\nresults = hipporag.rag_qa(\n queries=queries,\n gold_docs=gold_docs,\n gold_answers=answers\n)\n```\n\n## Graph Types\n\nThe framework supports configurable graph structures:\n\n| Graph Type | Description |\n|------------|-------------|\n| `facts_and_sim_passage_node_unidirectional` | Facts with similarity-based passage connections (default) |\n\nGraph edges include:\n- **Fact-to-Fact edges**: Created from OpenIE extractions\n- **Synonymy edges**: Based on embedding similarity above threshold\n- **Passage edges**: Connect passages to their extracted facts\n\n## Dependencies\n\nKey package dependencies managed in `setup.py`:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `torch` | `2.5.1` | Deep learning framework |\n| `transformers` | `4.45.2` | Model architectures |\n| `vllm` | `0.6.6.post1` | LLM inference |\n| `openai` | `1.91.1` | OpenAI API client |\n| `gritlm` | `1.0.2` | GritLM embedding model |\n| `networkx` | `3.4.2` | Graph operations |\n| `python_igraph` | `0.11.8` | Graph algorithms |\n| `pydantic` | `2.10.4` | Configuration validation |\n| `tiktoken` | `0.7.0` | Tokenization |\n\n资料来源：[setup.py:15-30]()\n\n## Error Handling\n\nThe framework uses `tenacity` for retry mechanisms with configurable backoff strategies when interacting with external APIs (OpenAI, Azure, vLLM).\n\n## Persistence\n\nAll indexed data is persisted to the `save_dir` directory with the following structure:\n\n```\nsave_dir/\n└── {llm_model_name}_{embedding_model_name}/\n ├── knowledge_graph.pkl # Serialized graph\n ├── passages.pkl # Passage embeddings\n ├── fact_nodes.pkl # Extracted facts\n └── config.json # Configuration snapshot\n\n---\n\n\n\n## Knowledge Graph and Retrieval\n\n### 相关页面\n\n相关主题：[Embedding Store and Management](#page-6), [LLM Integrations](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/utils/embed_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/embed_utils.py)\n- [src/hipporag/utils/qa_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/qa_utils.py)\n- [src/hipporag/rerank.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/rerank.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/llm/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/llm/__init__.py)\n- [src/hipporag/evaluation/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/evaluation/__init__.py)\n- [src/hipporag/retrieval/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/retrieval/__init__.py)\n \n\n# Knowledge Graph and Retrieval\n\n## Overview\n\nHippoRAG implements a neurobiologically inspired retrieval system that combines knowledge graph construction with advanced retrieval algorithms. The system is designed to enable LLMs to identify and leverage connections within new knowledge for improved retrieval performance. 资料来源：[setup.py:8]()\n\nThe Knowledge Graph and Retrieval module forms the core of HippoRAG's architecture, providing mechanisms to:\n\n- Extract factual knowledge from text passages using Open Information Extraction (OpenIE)\n- Construct heterogeneous graphs with multiple node and edge types\n- Perform personalized PageRank (PPR) based retrieval over the constructed graphs\n- Support incremental updates and document deletion operations\n\n资料来源：[src/hipporag/utils/config_utils.py:48-72]()\n\n## Architecture\n\n### High-Level System Design\n\nHippoRAG's retrieval system integrates several key components working in concert to provide accurate and efficient knowledge retrieval:\n\n```mermaid\ngraph TD\n A[Input Documents] --> B[OpenIE Processing]\n B --> C[Knowledge Graph Construction]\n C --> D[Embedding Generation]\n D --> E[Synonymy Edge Building]\n C --> F[Hybrid Graph]\n \n G[Query Input] --> H[Query Embedding]\n H --> I[Personalized PageRank]\n I --> F\n F --> J[Retrieval Results]\n J --> K[Reranking]\n K --> L[Final QA Output]\n \n M[LLM Inference] --> L\n```\n\n### Graph Construction Pipeline\n\nThe graph construction process transforms raw text into a structured knowledge representation:\n\n```mermaid\ngraph LR\n A[Passages] --> B[OpenIE Extractor]\n B --> C[Triplets/Entities]\n C --> D[Fact Nodes]\n \n E[Passages] --> F[Embedding Model]\n F --> G[Passage Embeddings]\n G --> H[Passage Nodes]\n \n D --> I[Passage-Fact Edges]\n H --> I\n \n G --> J[Synonymy Edges]\n J --> K[knn Retrieval]\n K --> L[Similarity Threshold Filter]\n L --> M[Synonymy Edge Network]\n```\n\n## Knowledge Graph Components\n\n### Node Types\n\n| Node Type | Description | Attributes |\n|-----------|-------------|------------|\n| Passage Nodes | Represent original text passages | idx, title, text, embedding |\n| Fact Nodes | Extracted facts/triplets from OpenIE | subject, predicate, object, embedding |\n\n### Edge Types\n\n| Edge Type | Source | Target | Purpose |\n|-----------|--------|--------|---------|\n| Passage-to-Fact | Passage Node | Fact Node | Links passages to their extracted facts |\n| Fact-to-Fact | Fact Node | Fact Node | Connects semantically related facts |\n| Synonymy | Passage Node | Passage Node | Links passages with high semantic similarity |\n| Bidirectional | Both | Both | Full edge in both directions |\n\n资料来源：[src/hipporag/utils/config_utils.py:70-85]()\n\n### Graph Types Configuration\n\nThe system supports multiple graph configurations via the `graph_type` parameter:\n\n| Graph Type | Description |\n|------------|-------------|\n| `facts_and_sim_passage_node_unidirectional` | Facts + similar passage nodes, unidirectional edges |\n| `facts_and_sim_passage_node_bidirectional` | Facts + similar passage nodes, bidirectional edges |\n| Custom types | Extensible graph construction patterns |\n\n资料来源：[main.py:18]()\n\n## Retrieval Process\n\n### Personalized PageRank (PPR) Algorithm\n\nHippoRAG uses Personalized PageRank for graph-based retrieval, which allows queries to propagate through the knowledge graph to identify relevant nodes.\n\n```mermaid\ngraph TD\n A[Query] --> B[Query Embedding]\n B --> C[Initial PPR Scores]\n C --> D[Graph Propagation]\n D --> E{Iteration}\n E -->|Continue| F[Score Aggregation]\n F --> D\n E -->|Converge| G[Top-K Selection]\n G --> H[Linked Nodes]\n \n I[damping factor: 0.5] --> D\n J[linking_top_k: 5] --> G\n```\n\n### Retrieval Configuration Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `retrieval_top_k` | 200 | Number of documents retrieved at each step |\n| `linking_top_k` | 5 | Number of linked nodes at each retrieval step |\n| `damping` | 0.5 | Damping factor for PPR algorithm |\n| `qa_top_k` | 5 | Top-k documents fed to QA model |\n\n资料来源：[src/hipporag/utils/config_utils.py:60-72]()\n\n### Synonymy Edge Construction\n\nSynonymy edges connect passages with high semantic similarity, enabling cross-document retrieval:\n\n```mermaid\ngraph TD\n A[All Passage Embeddings] --> B[KNN Retrieval]\n B --> C[Top-K Candidates]\n C --> D{Similarity > Threshold?}\n D -->|Yes| E[Create Synonymy Edge]\n D -->|No| F[Discard]\n E --> G[Synonymy Edge Network]\n```\n\n#### Synonymy Edge Parameters\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `synonymy_edge_topk` | 2047 | k for knn retrieval in building synonymy edges |\n| `synonymy_edge_query_batch_size` | 1000 | Batch size for query embeddings |\n| `synonymy_edge_key_batch_size` | 10000 | Batch size for key embeddings |\n| `synonymy_edge_sim_threshold` | 0.8 | Similarity threshold for candidate synonymy nodes |\n\n资料来源：[src/hipporag/utils/config_utils.py:73-85]()\n\n## Embedding Integration\n\n### Embedding Model Configuration\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `embedding_model_name` | - | Name of the embedding model |\n| `embedding_batch_size` | 16 | Batch size for embedding calls |\n| `embedding_return_as_normalized` | True | Whether to normalize embeddings |\n| `embedding_max_seq_len` | 2048 | Maximum sequence length |\n| `embedding_model_dtype` | auto | Data type for local models (float16/float32/bfloat16/auto) |\n\n资料来源：[src/hipporag/utils/config_utils.py:40-54]()\n\n### Supported Embedding Models\n\nThe system integrates with multiple embedding model providers:\n\n- **NV-Embed-v2**: NVIDIA's embedding model\n- **GritLM**: GritLM embedding model\n- **Contriever**: Facebook's dense retriever\n- **OpenAI Compatible**: Any OpenAI-compatible embedding endpoint\n- **Azure OpenAI**: Azure-hosted embedding models\n\n## Reranking Module\n\nAfter initial retrieval, HippoRAG applies reranking to improve result quality. The reranking module reorders retrieved candidates using additional scoring mechanisms.\n\n```mermaid\ngraph LR\n A[Retrieved Candidates] --> B[Reranker Model]\n B --> C[Relevance Scores]\n C --> D[Ranked Results]\n D --> E[Top Results]\n```\n\n资料来源：[src/hipporag/rerank.py]()\n\n## QA Integration\n\n### Multi-Step Retrieval and Reasoning\n\nHippoRAG supports interleaved retrieval and reasoning with configurable steps:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `max_qa_steps` | 1 | Maximum steps for interleaved retrieval and reasoning |\n| `qa_top_k` | 5 | Number of documents for QA model to process |\n\n资料来源：[src/hipporag/utils/config_utils.py:68-72]()\n\n### QA Pipeline Flow\n\n```mermaid\ngraph TD\n A[Query] --> B[QA Step 1]\n B --> C[Retrieval]\n C --> D[Read Documents]\n D --> E{More Steps Needed?}\n E -->|Yes| F[Update Context]\n F --> B\n E -->|No| G[Final Answer]\n \n H[gold_docs] --> I[Evaluation]\n I --> J[Metrics]\n J --> K[Recall, EM, F1]\n```\n\n## Data Formats\n\n### Corpus JSON Structure\n\n```json\n[\n {\n \"title\": \"PASSAGE TITLE\",\n \"text\": \"PASSAGE TEXT\",\n \"idx\": 0\n }\n]\n```\n\n### Query JSON Structure\n\n```json\n[\n {\n \"id\": \"question_id\",\n \"question\": \"QUESTION TEXT\",\n \"answer\": [\"ANSWER\"],\n \"answerable\": true,\n \"paragraphs\": [\n {\n \"title\": \"SUPPORTING TITLE\",\n \"text\": \"SUPPORTING TEXT\",\n \"is_supporting\": true,\n \"idx\": 0\n }\n ]\n }\n]\n```\n\n## Usage Examples\n\n### Basic Retrieval with 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# Index documents\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\nhipporag.index(docs)\n\n# Query with evaluation\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资料来源：[README.md:Quick_Start](), [tests_openai.py:22-60]()\n\n### Incremental Updates\n\n```python\n# Add new documents\nnew_docs = [\n \"Tom Hort's birthplace is Montebello.\",\n \"Sam Hort's birthplace is Montebello.\"\n]\nhipporag.index(docs=new_docs)\n\n# Delete documents\ndocs_to_delete = [\n \"Tom Hort's birthplace is Montebello.\",\n \"Sam Hort's birthplace is Montebello.\"\n]\nhipporag.delete(docs_to_delete)\n```\n\n资料来源：[tests_openai.py:61-82]()\n\n## Evaluation Metrics\n\nThe retrieval system is evaluated using standard information retrieval metrics:\n\n| Metric | Description |\n|--------|-------------|\n| Recall@k | Fraction of relevant documents in top-k |\n| EM | Exact Match accuracy |\n| F1 | Harmonic mean of precision and recall |\n\n## Summary\n\nThe Knowledge Graph and Retrieval module in HippoRAG provides a sophisticated pipeline for:\n\n1. **Knowledge Extraction**: Using OpenIE to extract factual triplets from text\n2. **Graph Construction**: Building heterogeneous graphs with passage nodes, fact nodes, and multiple edge types\n3. **Synonymy Discovery**: Creating semantic links between similar passages via embedding similarity\n4. **PPR-based Retrieval**: Performing personalized PageRank for graph-aware document retrieval\n5. **Reranking**: Refining retrieval results for improved accuracy\n6. **Incremental Updates**: Supporting document additions and deletions\n\nThis architecture enables HippoRAG to perform complex associativity and multi-hop reasoning tasks that traditional vector similarity retrieval cannot accomplish effectively.\n\n---\n\n\n\n## Embedding Store and Management\n\n### 相关页面\n\n相关主题：[LLM Integrations](#page-7), [Embedding Models](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/hipporag/embedding_store.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_store.py)\n- [src/hipporag/utils/embed_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/embed_utils.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/embedding_model/__init__.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/__init__.py)\n- [src/hipporag/embedding_model/base.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/embedding_model/base.py)\n \n\n# Embedding Store and Management\n\n## Overview\n\nThe Embedding Store and Management system in HippoRAG provides a unified interface for encoding text passages into vector embeddings, managing these embeddings throughout the indexing and retrieval lifecycle, and supporting multiple embedding model backends including NVIDIA NV-Embed-v2, GritLM, and Contriever. The system is designed to handle batch processing of documents with configurable parameters for sequence length, data type precision, and normalization behavior.\n\nHippoRAG's embedding management is tightly integrated with the knowledge graph construction process, where embeddings serve dual purposes: enabling semantic similarity search for passage linking and powering the retrieval phase through Personalized PageRank (PPR) algorithms. The embedding store abstracts away the underlying model implementation details, allowing the framework to switch between different embedding providers without changing the core indexing and retrieval logic.\n\n资料来源：[src/hipporag/utils/config_utils.py:1-50]()\n\n## Architecture\n\n### High-Level Components\n\nThe embedding system consists of three primary layers that work together to provide embedding services throughout the HippoRAG pipeline.\n\nThe **Model Layer** contains implementations for specific embedding models, each inheriting from a common base class that enforces a consistent interface. Currently supported models include NV-Embed-v2, GritLM, and Contriever, with the architecture supporting easy extension to additional models. Each model implementation handles the specific requirements of its underlying transformer architecture, including tokenizer configuration, padding strategies, and model-specific inference optimizations.\n\nThe **Utility Layer** provides helper functions for common embedding operations such as batch processing, embedding normalization, and similarity computation. These utilities ensure consistent handling of embeddings across different contexts and help optimize memory usage during large-scale indexing operations.\n\nThe **Configuration Layer** defines the parameters that control embedding behavior, including batch sizes, sequence length limits, and model-specific settings. This layer connects the embedding system to HippoRAG's global configuration management, allowing users to customize embedding behavior without modifying code.\n\n```mermaid\ngraph TD\n A[Documents] --> B[Embedding Store]\n B --> C[Model Layer
NV-Embed-v2
GritLM
Contriever]\n B --> D[Utility Layer
Batch Processing
Normalization]\n C --> E[Vector Storage]\n D --> E\n E --> F[Graph Construction]\n E --> G[Retrieval Phase]\n```\n\n资料来源：[src/hipporag/embedding_store.py:1-30]()\n\n### Data Flow\n\nDuring the **indexing phase**, documents are first processed by the embedding store to generate passage vectors. These vectors are stored alongside the passage metadata and serve as the foundation for graph construction. The embedding store processes passages in configurable batch sizes to balance memory usage and throughput, with the default batch size set to 16 documents per batch.\n\nDuring the **retrieval phase**, incoming queries are encoded using the same embedding model to produce a query vector. This query vector is then used for similarity computation against the indexed passage vectors, enabling semantic matching between the query intent and stored knowledge. The retrieval system can perform k-nearest neighbor (kNN) searches over the embedding space to identify candidate passages for further processing.\n\n```mermaid\ngraph LR\n A[Indexing Flow] --> B[Input Documents]\n B --> C[Batch Processing
batch_size=16]\n C --> D[Embedding Encoding]\n D --> E[Normalized Vectors]\n E --> F[Vector Storage]\n \n G[Retrieval Flow] --> H[Query Text]\n H --> I[Query Encoding]\n I --> J[Similarity Search]\n J --> K[kNN Retrieval
top-k candidates]\n K --> L[Ranked Passages]\n```\n\n资料来源：[src/hipporag/utils/embed_utils.py:1-25]()\n\n## Configuration Parameters\n\nThe embedding system is controlled through several configuration parameters defined in the global configuration structure. These parameters allow fine-tuning of embedding behavior for different hardware configurations and use cases.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `embedding_batch_size` | int | 16 | Number of documents processed in each embedding batch |\n| `embedding_return_as_normalized` | bool | true | Whether to L2-normalize output embeddings |\n| `embedding_max_seq_len` | int | 2048 | Maximum sequence length in tokens for the embedding model |\n| `embedding_model_dtype` | Literal | \"auto\" | Data type for local embedding models: float16, float32, bfloat16, or auto |\n| `embedding_model_name` | str | varies | Identifier for the embedding model (e.g., \"nvidia/NV-Embed-v2\") |\n| `embedding_base_url` | str | None | Base URL for OpenAI-compatible embedding endpoints |\n| `synonymy_edge_topk` | int | 2047 | k value for kNN retrieval when building synonymy edges |\n| `synonymy_edge_sim_threshold` | float | 0.8 | Minimum similarity threshold for synonymy edge candidates |\n\n资料来源：[src/hipporag/utils/config_utils.py:15-40]()\n\n## Embedding Model Interface\n\n### Base Class Contract\n\nAll embedding models must inherit from `BaseEmbeddingModel`, which defines the core interface that HippoRAG expects. The base class enforces implementation of the `__call__` method that accepts text inputs and returns embeddings, ensuring polymorphism across different model implementations.\n\nThe base class also defines the `EmbeddingConfig` dataclass that encapsulates model-specific settings. This configuration includes the model name, batch size, maximum sequence length, and data type settings. The configuration object is passed to the embedding model during initialization and can be modified to adjust model behavior without recreating the model instance.\n\n### Supported Models\n\n**NV-Embed-v2** is the primary embedding model recommended for production use, developed by NVIDIA. It provides high-quality sentence embeddings optimized for retrieval tasks. The model is accessed through HuggingFace and supports automatic device placement based on available GPU resources.\n\n**GritLM** provides an alternative embedding approach that combines retrieval and generation capabilities. It can serve both as an embedding model and as a decoder for generation tasks, offering flexibility in deployment configurations.\n\n**Contriever** is an open-source bi-encoder model for dense retrieval, useful for scenarios requiring a completely open-source embedding solution without proprietary dependencies.\n\n资料来源：[src/hipporag/embedding_model/__init__.py:1-20]()\n\n## Embedding Store API\n\n### Initialization\n\nThe embedding store is typically instantiated through the main HippoRAG class rather than directly. When creating a HippoRAG instance, the embedding model name and optional endpoint configuration are passed as parameters:\n\n```python\nhipporag = HippoRAG(\n save_dir=\"outputs\",\n llm_model_name=\"gpt-4o-mini\",\n embedding_model_name=\"nvidia/NV-Embed-v2\"\n)\n```\n\nFor OpenAI-compatible embedding endpoints, the base URL can be specified:\n\n```python\nhipporag = HippoRAG(\n save_dir=\"outputs\",\n llm_model_name=\"gpt-4o-mini\",\n embedding_model_name=\"text-embedding-3-small\",\n embedding_base_url=\"https://api.openai.com/v1\"\n)\n```\n\n资料来源：[README.md:1-50]()\n\n### Encoding Operations\n\nThe embedding store provides batch encoding capabilities for processing multiple documents efficiently. The encoding operation returns normalized embeddings by default, which is required for proper similarity computation during retrieval. The normalization is L2 normalization, ensuring that all embedding vectors have unit length.\n\nFor Azure OpenAI deployments, specialized endpoint parameters are supported:\n\n```python\nhipporag = HippoRAG(\n save_dir=\"save_dir\",\n llm_model_name=\"gpt-4o-mini\",\n embedding_model_name=\"text-embedding-3-small\",\n azure_endpoint=\"https://[ENDPOINT].openai.azure.com/...\",\n azure_embedding_endpoint=\"https://[ENDPOINT].openai.azure.com/...\"\n)\n```\n\n资料来源：[demo_azure.py:1-30]()\n\n## Integration with Knowledge Graph\n\nThe embedding system plays a critical role in HippoRAG's knowledge graph construction phase. After passages are indexed and encoded, the embeddings are used for two key graph-related operations.\n\n**Synonymy Edge Construction** uses embeddings to identify semantically similar passage pairs that should be connected in the knowledge graph. The system performs k-nearest neighbor searches over the passage embedding space, where the `synonymy_edge_topk` parameter controls how many candidates are considered for each passage. The `synonymy_edge_sim_threshold` parameter filters these candidates, with only pairs exceeding the similarity threshold being connected as synonymy edges.\n\n**Retrieval-Graph Linking** during the PPR retrieval process uses passage embeddings to establish the connection between the query and the knowledge graph. The query embedding enables the system to identify the most relevant starting nodes in the graph for the random walk algorithm.\n\n资料来源：[src/hipporag/utils/config_utils.py:30-45]()\n\n## Memory Management and Optimization\n\n### Batch Processing Strategy\n\nThe embedding store implements batch processing to optimize GPU memory utilization and throughput. The batch size is configurable via `embedding_batch_size` with a default of 16, meaning 16 documents are processed simultaneously during encoding. For systems with larger GPU memory, increasing this value can significantly improve indexing performance.\n\nThe system also supports separate batch sizes for the synonymy edge construction phase. The `synonymy_edge_query_batch_size` (default 1000) controls how many passage embeddings are queried at once during kNN search, while `synonymy_edge_key_batch_size` (default 10000) controls the key batch size for the search index.\n\n### Data Type Selection\n\nThe `embedding_model_dtype` parameter allows selection of the precision for local embedding models. The \"auto\" setting allows the system to select an appropriate default based on the hardware and model. Available options include float16 for memory-constrained environments, float32 for maximum precision, and bfloat16 which offers a good balance of range and memory efficiency on newer GPUs.\n\n资料来源：[src/hipporag/utils/config_utils.py:25-35]()\n\n## Error Handling and Resilience\n\nThe embedding system is designed with error handling patterns compatible with HippoRAG's overall resilience strategy. Batch processing allows partial failures to be identified and retried without losing all progress. The configuration system supports specifying fallback models or endpoints for production deployments requiring high availability.\n\nTenacity is used for retry logic in the embedding utilities, ensuring transient network failures or temporary service unavailability do not cause complete pipeline failures. This is particularly important when using remote embedding endpoints that may experience temporary connectivity issues.\n\n资料来源：[setup.py:1-30]()\n\n## Performance Considerations\n\nWhen optimizing HippoRAG for production deployment, the embedding configuration should be tuned based on the available hardware and expected workload characteristics. The primary tuning parameters include batch size for indexing throughput, sequence length limits for handling long documents, and data type selection for memory-constrained environments.\n\nFor maximum retrieval quality, the default normalization behavior should be maintained as it ensures consistent similarity computation across the retrieval pipeline. Disabling normalization may lead to suboptimal retrieval results as the similarity metrics assume unit-normalized vectors.\n\n资料来源：[src/hipporag/utils/config_utils.py:18-22]()\n\n## Related Components\n\nThe embedding system interacts closely with several other HippoRAG components. The Information Extraction module uses embeddings for processing extracted facts, the retrieval module depends on embeddings for kNN search and PPR initialization, and the evaluation module uses embeddings for computing retrieval metrics such as recall and MRR.\n\nThe embedding model implementations in `src/hipporag/embedding_model/` follow a consistent interface defined in `base.py`, allowing the embedding store to work with any model that adheres to this contract.\n\n---\n\n\n\n## LLM Integrations\n\n### 相关页面\n\n相关主题：[Embedding Models](#page-8), [Deployment Options](#page-10)\n\n\nRelevant Source Files
\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 \n\n# LLM Integrations\n\nHippoRAG provides a flexible, pluggable architecture for integrating various Large Language Model (LLM) providers. This modular design enables the framework to support multiple inference backends including OpenAI, vLLM for local deployment, and AWS Bedrock, allowing researchers and developers to choose the most appropriate LLM backend for their specific use case and infrastructure requirements.\n\n## Architecture Overview\n\nThe LLM integration system follows a strategy pattern where a base abstract class defines the interface contract, and concrete implementations handle provider-specific details. This design ensures that the core HippoRAG logic remains independent of any particular LLM vendor while maintaining the ability to leverage specialized features offered by different providers.\n\n```mermaid\ngraph TD\n A[HippoRAG Core] --> B[LLM Base Class]\n B --> C[OpenAIGPT]\n B --> D[VLLMOffline]\n B --> E[BedrockLLM]\n B --> F[Custom LLM Adapter]\n \n C --> G[OpenAI API]\n D --> H[Local vLLM Server]\n E --> I[AWS Bedrock]\n```\n\nThe `BaseLLM` abstract class in `src/hipporag/llm/base.py` defines the common interface that all LLM adapters must implement, ensuring consistent behavior across different providers.\n\n## Supported LLM Providers\n\n### OpenAI Models\n\nHippoRAG supports all OpenAI chat completion models through the `OpenAIGPT` class. This integration allows users to leverage the GPT family of models for both information extraction and question answering tasks.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model_name` | string | required | OpenAI model identifier (e.g., `gpt-4o-mini`, `gpt-4o`) |\n| `api_key` | string | env `OPENAI_API_KEY` | OpenAI API authentication key |\n| `base_url` | string | `https://api.openai.com/v1` | API endpoint base URL |\n| `max_tokens` | int | `None` | Maximum tokens in generated response |\n| `temperature` | float | `0.0` | Sampling temperature for generation |\n\n**Usage Example:**\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\n资料来源：[README.md:67-72](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### vLLM Local Deployment\n\nFor scenarios requiring local inference, HippoRAG supports vLLM-deployed models through the `VLLMOffline` class. This approach is particularly useful for privacy-sensitive applications, cost reduction at scale, or when working with custom fine-tuned models.\n\n**Server Setup:**\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.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:93-101](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n**Configuration Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model_name` | string | required | Model identifier for vLLM server |\n| `base_url` | string | required | vLLM server endpoint URL |\n| `openie_mode` | string | `\"online\"` | Mode for OpenIE processing (`online` or `offline`) |\n| `max_tokens` | int | `None` | Maximum tokens in generated response |\n| `temperature` | float | `0.0` | Sampling temperature for generation |\n\n**Offline Mode for OpenIE:**\n\nThe vLLM integration supports an offline mode where OpenIE extraction runs separately from the main pipeline. This is useful for debugging or when OpenIE results can be cached and reused.\n\n```python\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资料来源：[README.md:130-135](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### AWS Bedrock\n\nHippoRAG integrates with AWS Bedrock through the `BedrockLLM` class, enabling access to various foundation models hosted on AWS infrastructure. This integration is designed for enterprise deployments requiring scalable, managed LLM services.\n\n**Configuration Parameters:**\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `model_name` | string | required | Bedrock model identifier |\n| `aws_region` | string | `\"us-east-1\"` | AWS region for Bedrock endpoint |\n| `max_tokens` | int | `None` | Maximum tokens in generated response |\n| `temperature` | float | `0.0` | Sampling temperature for generation |\n\n### Azure OpenAI\n\nFor enterprise users with Azure OpenAI deployments, HippoRAG provides direct integration with Azure endpoints.\n\n**Configuration Example:**\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='gpt-4o-mini',\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资料来源：[demo_azure.py:16-21](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.py)\n\n## Base LLM Interface\n\nAll LLM adapters inherit from the `BaseLLM` abstract class, which defines the core contract for LLM interactions.\n\n```mermaid\nclassDiagram\n class BaseLLM {\n <>\n +generate(prompt: str) str\n +batch_generate(prompts: List[str]) List[str]\n +get_model_name() str\n }\n \n class OpenAIGPT {\n +generate(prompt: str) str\n +batch_generate(prompts: List[str]) List[str]\n }\n \n class VLLMOffline {\n +generate(prompt: str) str\n +batch_generate(prompts: List[str]) List[str]\n }\n \n class BedrockLLM {\n +generate(prompt: str) str\n +batch_generate(prompts: List[str]) List[str]\n }\n \n BaseLLM <|-- OpenAIGPT\n BaseLLM <|-- VLLMOffline\n BaseLLM <|-- BedrockLLM\n```\n\n**Core Methods:**\n\n| Method | Parameters | Return Type | Description |\n|--------|------------|-------------|-------------|\n| `generate` | `prompt: str` | `str` | Generate a single response from a prompt |\n| `batch_generate` | `prompts: List[str]` | `List[str]` | Generate responses for multiple prompts in batch |\n| `get_model_name` | None | `str` | Return the configured model identifier |\n\n## OpenIE Integration\n\nOpen Information Extraction (OpenIE) is a critical component of HippoRAG's knowledge graph construction pipeline. The LLM integration system supports multiple OpenIE modes to accommodate different deployment scenarios.\n\n```mermaid\ngraph LR\n A[Documents] --> B{HippoRAG}\n B --> C{OpenIE Mode}\n \n C -->|online| D[Real-time OpenIE]\n C -->|offline| E[Cached OpenIE Results]\n \n D --> F[OpenIE with LLM]\n E --> G[Load from JSON]\n \n F --> H[Knowledge Graph]\n G --> H\n```\n\n**OpenIE Implementation Classes:**\n\n| Class | Provider | Use Case |\n|-------|----------|----------|\n| `OpenAI_GPT` | OpenAI API | Cloud-based OpenIE extraction |\n| `VLLM_Offline` | Local vLLM | Private/onsite OpenIE extraction |\n\n资料来源：[README.md:47-48](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Configuration Schema\n\nThe LLM integration configuration is defined through the `HippoRAGConfig` class, which validates and manages all LLM-related settings.\n\n**Configuration Fields:**\n\n| Field | Type | Default | Description |\n|-------|------|---------|-------------|\n| `llm_name` | string | required | LLM model identifier |\n| `llm_base_url` | string | `None` | Base URL for LLM API endpoint |\n| `llm_max_tokens` | int | `None` | Maximum tokens per generation |\n| `llm_temperature` | float | `0.0` | Sampling temperature |\n| `openie_mode` | string | `\"online\"` | OpenIE processing mode |\n| `skip_graph` | bool | `False` | Skip graph construction step |\n\n资料来源：[main.py:18-26](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n## Workflow Integration\n\nThe following diagram illustrates how LLM integrations fit into the HippoRAG indexing and retrieval pipeline:\n\n```mermaid\ngraph TD\n subgraph Indexing\n A1[Input Documents] --> A2[Chunking]\n A2 --> A3[Embedding Generation]\n A3 --> A4[OpenIE with LLM]\n A4 --> A5[Knowledge Graph Construction]\n A5 --> A6[Graph Indexing]\n end\n \n subgraph Retrieval & QA\n B1[User Query] --> B2[Query Embedding]\n B2 --> B3[Graph Traversal]\n B3 --> B4[LLM for Answer Synthesis]\n B4 --> B5[Final Answer]\n end\n \n A4 -.->|Uses| LLM1[LLM Adapter]\n B4 -.->|Uses| LLM1\n```\n\n## Environment Variables\n\nProper configuration of environment variables is essential for LLM integrations to function correctly.\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `OPENAI_API_KEY` | For OpenAI | OpenAI API authentication key |\n| `HF_HOME` | For vLLM | Hugging Face cache directory |\n| `CUDA_VISIBLE_DEVICES` | For GPU | Comma-separated GPU device IDs |\n| `AWS_ACCESS_KEY_ID` | For Bedrock | AWS access credentials |\n| `AWS_SECRET_ACCESS_KEY` | For Bedrock | AWS secret credentials |\n\n资料来源：[README.md:58-66](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Testing LLM Integrations\n\nHippoRAG provides dedicated test scripts to verify LLM integration functionality.\n\n### OpenAI Test\n\n```bash\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n### Local vLLM Test\n\n```bash\n# Terminal 1: Start vLLM server\nexport CUDA_VISIBLE_DEVICES=0\nvllm serve meta-llama/Llama-3.1-8B-Instruct --port 6578\n\n# Terminal 2: Run test\nCUDA_VISIBLE_DEVICES=1 python tests_local.py\n```\n\n资料来源：[README.md:137-148](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Error Handling and Retries\n\nThe LLM integrations leverage the `tenacity` library for automatic retry behavior with exponential backoff. This ensures robust operation when dealing with network issues or rate limiting from LLM providers.\n\nConfiguration options for retry behavior:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `max_attempts` | 3 | Maximum number of retry attempts |\n| `wait_exponential_multiplier` | 1000 | Initial wait time in milliseconds |\n| `wait_exponential_max` | 10000 | Maximum wait time in milliseconds |\n\n## Extending LLM Support\n\nTo add support for a new LLM provider, implement a new class that inherits from `BaseLLM` and implements the required abstract methods:\n\n```python\nfrom hipporag.llm.base import BaseLLM\n\nclass CustomLLM(BaseLLM):\n def __init__(self, model_name: str, **kwargs):\n self.model_name = model_name\n # Initialize provider-specific client\n \n def generate(self, prompt: str) -> str:\n # Implement generation logic\n pass\n \n def batch_generate(self, prompts: List[str]) -> List[str]:\n # Implement batch generation\n pass\n \n def get_model_name(self) -> str:\n return self.model_name\n```\n\n## Performance Considerations\n\nWhen selecting and configuring LLM integrations, consider the following factors:\n\n1. **Latency**: OpenAI APIs typically offer lower latency for small workloads, while vLLM provides better performance for high-throughput scenarios\n2. **Cost**: Local vLLM deployment eliminates API costs but requires GPU infrastructure\n3. **Privacy**: For sensitive data, local deployment via vLLM or Bedrock private endpoints is recommended\n4. **Model Size**: Larger models (e.g., Llama-3.3-70B) require more GPU memory but often provide better extraction quality\n\n---\n\n\n\n## Embedding Models\n\n### 相关页面\n\n相关主题：[Embedding Store and Management](#page-6), [LLM Integrations](#page-7)\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/__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 \n\n# Embedding Models\n\nHippoRAG provides a flexible, modular embedding model system that supports multiple embedding backends including NVIDIA's NV-Embed-v2, GritLM, HuggingFace Transformers, and vLLM endpoints. This modular architecture enables the system to generate high-quality text embeddings for both passage encoding and query understanding in the retrieval pipeline.\n\n## Architecture Overview\n\nThe embedding model subsystem follows a base class pattern with specialized implementations. All embedding models inherit from `BaseEmbeddingModel` which defines the common interface and configuration schema.\n\n```mermaid\ngraph TD\n A[HippoRAG Core] --> B[Embedding Model Factory]\n B --> C[BaseEmbeddingModel]\n C --> D[NVEmbedV2]\n C --> E[GritLM]\n C --> F[TransformersEmbeddingModel]\n C --> G[VLLMEmbeddingModel]\n```\n\nThe factory pattern in `__init__.py` dynamically instantiates the appropriate embedding model based on the model name prefix:\n\n| Prefix | Model Class | Backend |\n|--------|-------------|---------|\n| `nvidia/NV-Embed-v2` | `NVEmbedV2` | HuggingFace |\n| `GritLM` | `GritLM` | GritLM library |\n| `Transformers/` | `TransformersEmbeddingModel` | SentenceTransformers |\n| `VLLM/` | `VLLMEmbeddingModel` | vLLM endpoints |\n\n资料来源：[src/hipporag/embedding_model/__init__.py](src/hipporag/embedding_model/__init__.py)\n\n## Base Configuration\n\nThe `BaseEmbeddingModel` and `EmbeddingConfig` classes define the configuration schema used across all embedding implementations. Configuration parameters include:\n\n| Parameter | Default | Description |\n|-----------|---------|-------------|\n| `embedding_batch_size` | 16 | Batch size for encoding operations |\n| `embedding_return_as_normalized` | True | Whether to normalize output embeddings |\n| `embedding_max_seq_len` | 2048 | Maximum sequence length for tokenization |\n| `embedding_model_dtype` | \"auto\" | Data type: float16, float32, bfloat16, or auto |\n\n资料来源：[src/hipporag/utils/config_utils.py:16-35](src/hipporag/utils/config_utils.py)\n\n## Available Embedding Models\n\n### NV-Embed-v2\n\nThe `NVEmbedV2` class provides integration with NVIDIA's NV-Embed-v2 embedding model, a high-performance encoder optimized for retrieval tasks.\n\n```python\nclass NVEmbedV2(BaseEmbeddingModel):\n def __init__(self, global_config: BaseConfig, embedding_model_name: str) -> None:\n super().__init__(global_config=global_config)\n # Model initialization with HuggingFace transformers\n```\n\n资料来源：[src/hipporag/embedding_model/NVEmbedV2.py](src/hipporag/embedding_model/NVEmbedV2.py)\n\n### GritLM\n\nThe `GritLM` class wraps the GritLM library for generating embeddings with built-in instruction-following capabilities.\n\n```python\nclass GritLM(BaseEmbeddingModel):\n def __init__(self, global_config: BaseConfig, embedding_model_name: str) -> None:\n super().__init__(global_config=global_config)\n # GritLM-specific initialization\n```\n\n资料来源：[src/hipporag/embedding_model/GritLM.py](src/hipporag/embedding_model/GritLM.py)\n\n### Transformers (SentenceTransformers)\n\nThe `TransformersEmbeddingModel` class enables using any model from the HuggingFace ecosystem via the SentenceTransformers library. Select this implementation by using `embedding_model_name` that starts with `\"Transformers/\"`.\n\n```python\nclass TransformersEmbeddingModel(BaseEmbeddingModel):\n \"\"\"\n To select this implementation you can initialise HippoRAG with:\n embedding_model_name starts with \"Transformers/\"\n \"\"\"\n def __init__(self, global_config: BaseConfig, embedding_model_name: str) -> None:\n super().__init__(global_config=global_config)\n self.model_id = embedding_model_name[len(\"Transformers/\"):]\n self.batch_size = 64\n self.model = SentenceTransformer(\n self.model_id, \n device=\"cuda\" if torch.cuda.is_available() else \"cpu\"\n )\n```\n\nKey characteristics:\n- Automatically detects CUDA availability for GPU acceleration\n- Uses batch size of 64 for efficient processing\n- Extracts model ID by removing the `\"Transformers/\"` prefix\n\n资料来源：[src/hipporag/embedding_model/Transformers.py:1-40](src/hipporag/embedding_model/Transformers.py)\n\n### VLLM (Endpoint-based)\n\nThe `VLLMEmbeddingModel` class provides integration with OpenAI-compatible vLLM embedding endpoints. Select this implementation by using `embedding_model_name` that starts with `\"VLLM/\"`.\n\n```python\nclass VLLMEmbeddingModel(BaseEmbeddingModel):\n \"\"\"\n To select this implementation you can initialise HippoRAG with:\n embedding_model_name starts with \"VLLM/\"\n The embedding base url should contain the v1/embeddings.\n \"\"\"\n def __init__(self, global_config: BaseConfig, embedding_model_name: str) -> None:\n super().__init__(global_config=global_config)\n self.model_id = embedding_model_name[len(\"VLLM/\"):]\n self.batch_size = 32\n self.url = global_config.embedding_base_url\n```\n\nThe model communicates with the endpoint using the OpenAI embeddings API format:\n\n```python\npayload = {\n \"model\": self.model_id,\n \"input\": input_text,\n}\nresponse = requests.post(self.base_url, headers=headers, json=payload)\n```\n\n资料来源：[src/hipporag/embedding_model/VLLM.py:1-50](src/hipporag/embedding_model/VLLM.py)\n\n## Query Instructions\n\nEmbedding models support query instruction templates for improving retrieval relevance. The system uses instructions for mapping queries to facts and passages:\n\n```python\nself.search_query_instr = set([\n get_query_instruction('query_to_fact'),\n get_query_instruction('query_to_passage')\n])\n```\n\n资料来源：[src/hipporag/embedding_model/Transformers.py:23-27](src/hipporag/embedding_model/Transformers.py)\n\n## Usage Patterns\n\n### Quick Start with OpenAI-style Models\n\n```python\nhipporag = HippoRAG(\n save_dir=save_dir,\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\n### Using Custom Endpoints\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### Using vLLM Local Deployment\n\n```python\n# Start vLLM server\nvllm serve meta-llama/Llama-3.1-8B-Instruct --tensor-parallel-size 2\n\n# Configure with VLLM prefix\nhipporag = HippoRAG(\n save_dir=save_dir,\n llm_model_name='...',\n embedding_model_name='VLLM/your-model-name',\n embedding_base_url='http://localhost:8000/v1/embeddings'\n)\n```\n\n## Dependencies\n\nThe embedding model system depends on the following packages:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `transformers` | 4.45.2 | Core model loading |\n| `sentence-transformers` | (via Transformers) | Sentence encoding |\n| `gritlm` | 1.0.2 | GritLM embeddings |\n| `torch` | 2.5.1 | GPU acceleration |\n| `einops` | (latest) | Tensor operations |\n\n资料来源：[setup.py:19-32](setup.py)\n\n## Configuration Parameters Summary\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `embedding_batch_size` | int | 16 | Batch size for embedding inference |\n| `embedding_return_as_normalized` | bool | True | L2 normalize embeddings |\n| `embedding_max_seq_len` | int | 2048 | Maximum token sequence length |\n| `embedding_model_dtype` | str | \"auto\" | Model precision (float16/float32/bfloat16/auto) |\n\n资料来源：[src/hipporag/utils/config_utils.py:16-29](src/hipporag/utils/config_utils.py)\n\n---\n\n\n\n## Open Information Extraction (OpenIE)\n\n### 相关页面\n\n相关主题：[Knowledge Graph and Retrieval](#page-5), [LLM Integrations](#page-7)\n\n\nRelevant Source Files
\n\n以下源码文件用于生成本页说明：\n\n- [setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n- [src/hipporag/utils/config_utils.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/src/hipporag/utils/config_utils.py)\n- [main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.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\n \n\n# Open Information Extraction (OpenIE)\n\n## Overview\n\nOpen Information Extraction (OpenIE) is a critical component in the HippoRAG pipeline that enables the extraction of structured knowledge triples from unstructured text. The system extracts **entities**, **relations**, and **triples** from passages to construct a knowledge graph that mimics hippocampal memory formation in biological systems.\n\nIn HippoRAG, OpenIE serves as the foundation for building the associative memory graph. Extracted triples form **fact nodes** in the knowledge graph, enabling parametric nearest neighbor (PPR) retrieval that connects related information across documents.\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Architecture\n\nThe OpenIE system in HippoRAG supports multiple deployment modes and LLM backends:\n\n```mermaid\ngraph TD\n A[Unstructured Text] --> B[Information Extraction Module]\n B --> C{openie_mode}\n C -->|online| D[OpenAI GPT]\n C -->|offline| E[vLLM Offline]\n D --> F[Triple Extraction]\n E --> F\n F --> G[NER Processing]\n G --> H[Knowledge Triples]\n H --> I[Knowledge Graph Construction]\n```\n\n### Module Structure\n\n| Module | File | Purpose |\n|--------|------|---------|\n| Base Interface | `information_extraction/__init__.py` | Exports model classes |\n| OpenAI Integration | `openie_openai_gpt.py` | Online OpenIE via OpenAI API |\n| vLLM Offline | `openie_vllm_offline.py` | Offline batch processing with vLLM |\n| Triple Extraction Prompt | `prompts/templates/triple_extraction.py` | LLM prompt for triple extraction |\n| NER Prompt | `prompts/templates/ner.py` | LLM prompt for named entity recognition |\n\n资料来源：[README.md - Code Structure](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Configuration\n\n### ConfigUtils Class Parameters\n\nThe `InformationExtractionConfig` dataclass provides the following configuration options:\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `information_extraction_model_name` | `Literal[\"openie_openai_gpt\"]` | `\"openie_openai_gpt\"` | Class name indicating which information extraction model to use |\n| `openie_mode` | `Literal[\"offline\", \"online\"]` | `\"online\"` | Mode of the OpenIE model: `online` uses OpenAI API, `offline` uses vLLM batch processing |\n| `skip_graph` | `bool` | `False` | Whether to skip graph construction. Set to `True` when running vLLM offline indexing for the first time |\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### Main Entry Point Configuration\n\nIn the `main.py` script, OpenIE parameters are passed via command-line arguments:\n\n```python\nconfig = BaseConfig(\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 max_new_tokens=None,\n corpus_len=len(corpus),\n openie_mode=args.openie_mode # 'online' or 'offline'\n)\n```\n\n**Command-line arguments:**\n- `--openie_mode`: Choose between `online` (OpenAI API) or `offline` (vLLM)\n- `--force_openie_from_scratch`: If `False`, reuse existing OpenIE results if available\n\n资料来源：[main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n## Extraction Workflow\n\n### Triple Extraction Process\n\nThe triple extraction workflow follows these steps:\n\n```mermaid\nsequenceDiagram\n participant Text as Raw Text Input\n participant Triple as Triple Extraction Prompt\n participant LLM as Language Model\n participant NER as NER Prompt\n participant Output as Knowledge Triples\n \n Text->>Triple: Passage text\n Triple->>LLM: Structured prompt\n LLM->>Output: Subject-Predicate-Object triples\n Output->>NER: Named Entity Recognition\n NER->>LLM: Entity labels\n LLM->>Output: Typed entities\n```\n\n### Supported Deployment Modes\n\n| Mode | Backend | Use Case | API Key Required |\n|------|---------|----------|------------------|\n| `online` | OpenAI GPT | Quick testing, small corpora | Yes (`OPENAI_API_KEY`) |\n| `offline` | vLLM | Large-scale indexing, cost efficiency | No (local deployment) |\n\n## Knowledge Graph Integration\n\nOpenIE extracted triples are converted into graph structures:\n\n```mermaid\ngraph LR\n A[Passage Text] -->|OpenIE| B[Triple: Entity1 → Relation → Entity2]\n B --> C[Fact Node]\n C --> D[Knowledge Graph]\n D --> E[Personalized PageRank]\n E --> F[Associative Retrieval]\n```\n\nThe extracted triples serve dual purposes:\n\n1. **Fact Nodes**: Create direct connections between related entities\n2. **Association Links**: Enable multi-hop reasoning through the graph\n\nThis design mirrors the dentate gyrus pattern separation mechanism in the hippocampus, where similar memories are differentiated to reduce interference.\n\n资料来源：[README.md - Methodology](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Usage Examples\n\n### Online Mode (OpenAI)\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# OpenIE runs automatically during indexing\nhipporag.index(docs=[\"Passage containing facts to extract.\"])\n```\n\n### Offline Mode (vLLM)\n\n```bash\n# 1. Start vLLM server\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\n# 2. Run indexing with offline OpenIE\npython main.py --dataset sample --openie_mode offline\n```\n\n资料来源：[README.md - Quick Start](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Dependencies\n\nThe OpenIE system requires the following core dependencies:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `torch` | 2.5.1 | PyTorch backend |\n| `transformers` | 4.45.2 | Model architecture |\n| `openai` | 1.91.1 | Online OpenAI API |\n| `vllm` | 0.6.6.post1 | Offline inference |\n| `litellm` | 1.73.1 | Unified LLM interface |\n| `tqdm` | - | Progress bars |\n\n资料来源：[setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n\n## Extracted Data Format\n\nOpenIE produces structured triples in the following format:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `subject` | str | First entity |\n| `predicate` | str | Relation verb/phrase |\n| `object` | str | Second entity |\n| `context` | str | Source passage text |\n\nThese triples are then processed into graph nodes and edges for the knowledge graph construction phase.\n\n---\n\n\n\n## Deployment Options\n\n### 相关页面\n\n相关主题：[Installation and Setup](#page-1), [LLM Integrations](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\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- [demo_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.py)\n- [demo_local.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_local.py)\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- [README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n \n\n# Deployment Options\n\nHippoRAG supports multiple deployment configurations to accommodate different infrastructure requirements and use cases. This page documents the available deployment options, configuration parameters, and setup procedures for running HippoRAG in various environments.\n\n## Overview\n\nHippoRAG provides three primary deployment models:\n\n| Deployment Type | LLM Backend | Embedding Backend | Typical Use Case |\n|-----------------|-------------|-------------------|------------------|\n| **OpenAI API** | OpenAI hosted models | OpenAI/NVIDIA hosted | Quickstart, development |\n| **vLLM (Local)** | Self-hosted LLMs via vLLM | Local embedding models | Production, cost-sensitive |\n| **Azure OpenAI** | Azure-hosted models | Azure-hosted embeddings | Enterprise compliance |\n\n资料来源：[README.md](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Environment Setup\n\nRegardless of deployment type, certain environment variables must be configured:\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0,1,2,3\nexport HF_HOME=\n```\n\nFor OpenAI and Azure deployments, additional API credentials are required:\n\n```bash\nexport OPENAI_API_KEY=\n```\n\n资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## OpenAI API Deployment\n\nThe simplest deployment option uses OpenAI's hosted API endpoints for both LLM inference and embeddings.\n\n### Configuration Parameters\n\n| Parameter | Description | Example Value |\n|-----------|-------------|---------------|\n| `--llm_base_url` | OpenAI API endpoint | `https://api.openai.com/v1` |\n| `--llm_name` | OpenAI model identifier | `gpt-4o-mini` |\n| `--embedding_name` | Embedding model name | `nvidia/NV-Embed-v2` |\n\n### Running with OpenAI Models\n\n```bash\ndataset=sample\n\npython main.py --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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Programmatic Usage\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\n资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Local vLLM Deployment\n\nFor production environments or cost-sensitive deployments, HippoRAG supports self-hosted LLMs using vLLM.\n\n### Architecture\n\n```mermaid\ngraph TD\n A[HippoRAG Main Process] --> B[vLLM Server]\n A --> C[Local Embedding Model]\n B --> D[GPU 0-1]\n C --> D\n E[Indexing Pipeline] --> A\n F[QA Pipeline] --> A\n```\n\n### Starting vLLM Server\n\nLaunch the vLLM server with tensor parallelism for multi-GPU setups:\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资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Configuration Parameters\n\n| Parameter | Description | Default |\n|-----------|-------------|---------|\n| `--llm_base_url` | vLLM server endpoint | `http://localhost:6578/v1` |\n| `--llm_name` | Model name (must match deployed model) | `meta-llama/Llama-3.1-8B-Instruct` |\n| `--embedding_name` | Local embedding model identifier | `nvidia/NV-Embed-v2` |\n\n### Running Main Process\n\nWith vLLM server running on GPUs 0-1, run the main process on separate GPUs:\n\n```bash\nexport CUDA_VISIBLE_DEVICES=2,3\nexport HF_HOME=\n\npython main.py --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](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n## Azure OpenAI Deployment\n\nEnterprise deployments requiring Azure infrastructure can use Azure OpenAI endpoints.\n\n### Configuration Parameters\n\n| Parameter | CLI Argument | Description |\n|-----------|--------------|-------------|\n| `azure_endpoint` | `--azure_endpoint` | Azure OpenAI chat completions endpoint |\n| `azure_embedding_endpoint` | `--azure_embedding_endpoint` | Azure OpenAI embeddings endpoint |\n\n### Endpoint Format\n\n```python\nazure_endpoint = (\n \"https://[ENDPOINT_NAME].openai.azure.com/\"\n \"openai/deployments/gpt-4o-mini/chat/completions\"\n \"?api-version=2025-01-01-preview\"\n)\n\nazure_embedding_endpoint = (\n \"https://[ENDPOINT_NAME].openai.azure.com/\"\n \"openai/deployments/text-embedding-3-small/embeddings\"\n \"?api-version=2023-05-15\"\n)\n```\n\n资料来源：[demo_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.py)\n\n### Programmatic Usage\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 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\nhipporag.index(docs=docs)\n```\n\n资料来源：[demo_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/demo_azure.py)\n\n### CLI Usage\n\n```bash\npython main_azure.py \\\n --dataset sample \\\n --azure_endpoint \"https://[ENDPOINT].openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2025-01-01-preview\" \\\n --azure_embedding_endpoint \"https://[ENDPOINT].openai.azure.com/openai/deployments/text-embedding-3-small/embeddings?api-version=2023-05-15\" \\\n --save_dir outputs\n```\n\n资料来源：[main_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_azure.py)\n\n## Indexing Options\n\n### OpenIE Modes\n\nHippoRAG supports two Open Information Extraction (OpenIE) modes:\n\n| Mode | Description | Resource Usage |\n|------|-------------|----------------|\n| `online` | Uses OpenAI GPT for real-time extraction | API costs |\n| `offline` | Uses local vLLM batch processing | GPU compute |\n\n```bash\npython main.py --dataset $dataset --openie_mode offline\n```\n\n资料来源：[main.py:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py)\n\n### Force Rebuild Options\n\n| Parameter | Description |\n|-----------|-------------|\n| `--force_index_from_scratch` | Ignores existing storage and rebuilds from scratch |\n| `--force_openie_from_scratch` | Ignores cached OpenIE results and recomputes |\n\n```bash\npython main_azure.py \\\n --force_index_from_scratch true \\\n --force_openie_from_scratch true\n```\n\n资料来源：[main_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_azure.py)\n\n## StandardRAG vs HippoRAG\n\nThe codebase provides two RAG implementations selectable via configuration:\n\n```python\n# Standard HippoRAG (default)\nhipporag = HippoRAG(global_config=config)\n\n# Alternative DPR-style implementation\nhipporag = StandardRAG(global_config=config)\n```\n\n资料来源：[main.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main.py) and [main_dpr.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/main_dpr.py)\n\n## Installation Requirements\n\nAll deployment options require the HippoRAG package and its dependencies:\n\n```bash\nconda create -n hipporag python=3.10\nconda activate hipporag\npip install hipporag\n```\n\nOr install from source:\n\n```bash\npip install -e .\n```\n\nCore dependencies include:\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| `torch` | 2.5.1 | Deep learning framework |\n| `transformers` | 4.45.2 | Model loading |\n| `vllm` | 0.6.6.post1 | Local inference |\n| `openai` | 1.91.1 | API client |\n| `litellm` | 1.73.1 | Unified LLM interface |\n| `gritlm` | 1.0.2 | Embedding models |\n| `networkx` | 3.4.2 | Graph operations |\n| `pydantic` | 2.10.4 | Configuration validation |\n\n资料来源：[setup.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/setup.py)\n\n## Testing Deployments\n\n### OpenAI Test\n\n```bash\nexport OPENAI_API_KEY=\nconda activate hipporag\npython tests_openai.py\n```\n\n资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Local vLLM Test\n\n```bash\nexport CUDA_VISIBLE_DEVICES=0\nexport VLLM_WORKER_MULTIPROC_METHOD=spawn\nexport HF_HOME=\n\n# Start vLLM server\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# Run tests\nCUDA_VISIBLE=1 python tests_local.py\n```\n\n资料来源：[README.md:1](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/README.md)\n\n### Azure Test\n\n```bash\npython tests_azure.py\n```\n\n资料来源：[tests_azure.py](https://github.com/OSU-NLP-Group/HippoRAG/blob/main/tests_azure.py)\n\n## Deployment Decision Matrix\n\n| Criteria | OpenAI API | vLLM Local | Azure |\n|----------|------------|------------|-------|\n| Setup complexity | Low | High | Medium |\n| Cost | Pay-per-use | GPU infrastructure | Azure subscription |\n| Data privacy | Data leaves your environment | All data stays local | Configurable |\n| Latency | Network dependent | Local, optimized | Network dependent |\n| Model flexibility | Limited to API models | Any HuggingFace model | Limited to deployed models |\n| Recommended for | Development, prototyping | Production, research | Enterprise compliance |\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> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for OSU-NLP-Group/HippoRAG.\n\nProject:\n- Name: HippoRAG\n- Repository: https://github.com/OSU-NLP-Group/HippoRAG\n- Summary: HippoRAG 2: From RAG to Memory
\n- Host target: chatgpt\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: HippoRAG 2: From RAG to Memory
\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: HippoRAG 2: From RAG to Memory
\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. page-1: Installation and Setup. Produce one small intermediate artifact and wait for confirmation.\n2. page-2: Quick Start Guide. Produce one small intermediate artifact and wait for confirmation.\n3. page-4: HippoRAG Core Class. Produce one small intermediate artifact and wait for confirmation.\n4. page-5: Knowledge Graph and Retrieval. Produce one small intermediate artifact and wait for confirmation.\n5. page-7: LLM Integrations. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/OSU-NLP-Group/HippoRAG\n- https://github.com/OSU-NLP-Group/HippoRAG#readme\n- requirements.txt\n- setup.py\n- README.md\n- demo.py\n- demo_openai.py\n- src/hipporag/HippoRAG.py\n- src/hipporag/StandardRAG.py\n- src/hipporag/utils/embed_utils.py\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\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"
}