{ "canonical_name": "QuivrHQ/quivr", "compilation_id": "pack_89fa263f2ba14a7baa8c8b762fe532b8", "created_at": "2026-05-21T18:55:26.007889+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight", "recommended_asset_types=mcp_config, 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 quivr-core` 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 quivr-core", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_4e8fb4508b7a40b0bede44dff077ac79" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_2c23d66dd834852a3b79de73f10bd4a3", "canonical_name": "QuivrHQ/quivr", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/QuivrHQ/quivr", "slug": "quivr", "source_packet_id": "phit_260effb2c10e4cfe9b03fac94a74d3be", "source_validation_id": "dval_cb34a15d24d14dc3a30e63e5b51ebb41" }, "merchandising": { "best_for": "需要信息检索与知识管理能力，并使用 chatgpt的用户", "github_forks": 3743, "github_stars": 39150, "one_liner_en": "Opiniated RAG for integrating GenAI in your apps 🧠 Focus on your product rather than the RAG. Easy integration in existing products with customisation! Any LLM: GPT4, Groq, Llama. Any Vectorstore: PGVector, Faiss. Any Files. Anyway you want.", "one_liner_zh": "Opiniated RAG for integrating GenAI in your apps 🧠 Focus on your product rather than the RAG. Easy integration in existing products with customisation! Any LLM: GPT4, Groq, Llama. Any Vectorstore: PGVector, Faiss. Any Files. Anyway you want.", "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": "quivr", "title_zh": "quivr 能力包", "visible_tags": [ { "label_en": "Knowledge Retrieval", "label_zh": "知识检索", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-knowledge-retrieval", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Structured Data Extraction", "label_zh": "结构化数据提取", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-structured-data-extraction", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Open Source Tool", "label_zh": "开源工具", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-open-source-tool", "type": "selection_signal" } ] }, "packet_id": "phit_260effb2c10e4cfe9b03fac94a74d3be", "page_model": { "artifacts": { "artifact_slug": "quivr", "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 quivr-core", "label": "Python / pip · 官方安装入口", "source": "https://github.com/QuivrHQ/quivr#readme", "verified": true } ], "display_tags": [ "知识检索", "知识库问答", "结构化数据提取", "节点式流程编排", "开源工具" ], "eyebrow": "信息检索与知识管理", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要信息检索与知识管理能力，并使用 chatgpt的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Opiniated RAG for integrating GenAI in your apps 🧠 Focus on your product rather than the RAG. Easy integration in existing products with customisation! Any LLM: GPT4, Groq, Llama. Any Vectorstore: PGVector, Faiss. Any Files. Anyway you want." }, { "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": "mcp_config, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：EU AI Act Compliance Scan Results — Sharing Findings for Feedback", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_46118108af95480ba852109be6e2c66a | https://github.com/QuivrHQ/quivr/issues/3667 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：EU AI Act Compliance Scan Results — Sharing Findings for Feedback", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]:", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_ff260ca3ab5247679b2ded201ec21e24 | https://github.com/QuivrHQ/quivr/issues/2004 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：[Bug]:", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Integration idea: Screenpipe for screen/audio context", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_3a7f345691d04bbea72b03858746645e | https://github.com/QuivrHQ/quivr/issues/3658 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：Integration idea: Screenpipe for screen/audio context", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_e3091b23b6184dffb982e0cc494134fd | https://github.com/QuivrHQ/quivr/issues/3650 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:640079149 | https://github.com/QuivrHQ/quivr | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：The garbage collector is trying to clean up non-checked-in connection >, which will…", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_e6fdde799a2b4f53806121190979025a | https://github.com/QuivrHQ/quivr/issues/3654 | 来源讨论提到 python 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：The garbage collector is trying to clean up non-checked-in connection 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 quivr 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Opiniated RAG for integrating GenAI in your apps 🧠 Focus on your product rather than the RAG. Easy integration in existing products with customisation! Any LLM: GPT4, Groq, Llama. Any Vectorstore: PGVector, Faiss. Any Files. Anyway you want. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-rag-flow：RAG 处理流程。围绕“RAG 处理流程”模拟一次用户任务，不展示安装或运行结果。\n5. page-brain：Brain 核心概念。围绕“Brain 核心概念”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-rag-flow\n输入：用户提供的“RAG 处理流程”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-brain\n输入：用户提供的“Brain 核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-rag-flow：Step 4 必须围绕“RAG 处理流程”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-brain：Step 5 必须围绕“Brain 核心概念”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/QuivrHQ/quivr\n- https://github.com/QuivrHQ/quivr#readme\n- README.md\n- core/README.md\n- core/quivr_core/__init__.py\n- examples/simple_question/simple_question.py\n- examples/simple_question/simple_question_streaming.py\n- examples/chatbot/main.py\n- core/quivr_core/brain/brain.py\n- core/quivr_core/rag/quivr_rag.py\n- core/quivr_core/rag/quivr_rag_langgraph.py\n- core/quivr_core/config.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 quivr 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: [Bug]:（https://github.com/QuivrHQ/quivr/issues/2004）；github/github_issue: Integration idea: Screenpipe for screen/audio context（https://github.com/QuivrHQ/quivr/issues/3658）；github/github_issue: [Bug]: RuntimeError: There is no current event loop in thread 'MainThrea（https://github.com/QuivrHQ/quivr/issues/3650）；github/github_issue: EU AI Act Compliance Scan Results — Sharing Findings for Feedback（https://github.com/QuivrHQ/quivr/issues/3667）；github/github_issue: The garbage collector is trying to clean up non-checked-in connection \n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速入门指南](#page-quickstart), [系统架构](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/QuivrHQ/quivr/blob/main/README.md)\n- [core/README.md](https://github.com/QuivrHQ/quivr/blob/main/core/README.md)\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/processor/processor_base.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/processor_base.py)\n- [examples/simple_question/simple_question.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question.py)\n- [examples/pdf_parsing_tika.py](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py)\n
\n\n# 项目概述\n\n## 项目简介\n\nQuivr 是一个开源的个人第二大脑（Second Brain）项目，利用生成式人工智能（Generative AI）技术帮助用户构建智能知识助手。该项目旨在为开发者提供一套快速、高效且可定制的检索增强生成（RAG）解决方案，使开发者能够专注于产品开发，而无需深入研究 RAG 技术的底层细节。\n\n资料来源：[README.md:1-15]()\n\n### 核心定位\n\nQuivr 的核心价值主张在于：\n\n- **开箱即用的 RAG 方案**：提供经过优化的检索增强生成工作流，开箱即用\n- **多模型支持**：兼容 OpenAI、Anthropic、Mistral、Gemma 等主流大语言模型\n- **任意文件类型支持**：支持 PDF、TXT、Markdown 等常见格式，并允许自定义解析器\n- **完全可定制**：支持添加互联网搜索、工具扩展等高级功能\n\n资料来源：[README.md:25-35]()\n\n## 技术架构\n\n### 整体架构\n\nQuivr 采用模块化架构设计，主要包含以下核心组件：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Brain 核心类]\n B --> C[RAG 工作流引擎]\n C --> D[检索模块]\n C --> E[重排序模块]\n C --> F[生成模块]\n D --> G[向量数据库]\n E --> G\n F --> H[LLM 大语言模型]\n G --> D\n```\n\n### 核心模块说明\n\n| 模块名称 | 功能描述 | 关键文件 |\n|---------|---------|---------|\n| Brain | 核心管理类，负责文件处理和查询编排 | `quivr_core/brain/brain.py` |\n| RAG | 检索增强生成引擎，处理检索和生成逻辑 | `quivr_core/rag/quivr_rag.py` |\n| Processor | 文件解析器，处理各种文件格式 | `quivr_core/processor/processor_base.py` |\n| Embeddings | 向量化模块，将文本转换为向量 | 配置可指定 |\n| LLM Endpoint | 大语言模型接口，支持多种模型 | `quivr_core/llm/llm_endpoint.py` |\n\n资料来源：[core/README.md:1-15]()\n\n## 快速入门\n\n### 环境要求\n\n| 要求 | 最低版本 |\n|-----|---------|\n| Python | 3.10+ |\n| pip | 最新版本 |\n\n资料来源：[README.md:50-55]()\n\n### 安装方式\n\n通过 pip 安装 quivr-core 核心包：\n\n```bash\npip install quivr-core\n```\n\n资料来源：[README.md:30-35]()\n\n### 5 行代码创建 RAG\n\n以下示例展示了如何使用 Quivr 构建一个简单的问答系统：\n\n```python\nimport tempfile\nfrom quivr_core import Brain\n\nif __name__ == \"__main__\":\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".txt\") as temp_file:\n temp_file.write(\"Gold is a liquid of blue-like colour.\")\n temp_file.flush()\n\n brain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[temp_file.name],\n )\n\n answer = brain.ask(\"what is gold? answer in french\")\n print(\"answer:\", answer)\n```\n\n资料来源：[README.md:38-55]()\n\n## Brain 核心类\n\n### 核心功能\n\n`Brain` 类是 Quivr 的核心入口点，封装了文件处理、向量存储和问答功能。该类提供了以下关键方法：\n\n| 方法名 | 功能描述 | 返回类型 |\n|-------|---------|---------|\n| `from_files` | 从文件创建 Brain 实例 | `Brain` |\n| `from_langchain_documents` | 从 LangChain 文档创建 Brain | `Brain` |\n| `asearch` | 异步搜索相关文档 | `list[SearchResult]` |\n| `ask` | 提问并获取回答 | `RAGResponse` |\n\n资料来源：[core/quivr_core/brain/brain.py:1-80]()\n\n### 文件处理流程\n\n```mermaid\ngraph LR\n A[上传文件] --> B[Processor 解析]\n B --> C[分块处理]\n C --> D[元数据提取]\n D --> E[语言检测]\n E --> F[向量数据库存储]\n```\n\n### 元数据处理\n\n每个文档块在处理时都会附加丰富的元数据信息：\n\n| 元数据字段 | 来源 | 说明 |\n|-----------|-----|------|\n| `chunk_index` | 自动生成 | 文档块索引 |\n| `quivr_core_version` | 系统信息 | Quivr 版本号 |\n| `language` | 自动检测 | 文档语言 |\n| `original_file_name` | 文件属性 | 原始文件名 |\n\n资料来源：[core/quivr_core/processor/processor_base.py:15-35]()\n\n## RAG 工作流配置\n\n### 工作流节点\n\nQuivr 支持通过 YAML 配置文件定义 RAG 工作流，包含以下标准节点：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"retrieve\"]\n - name: \"retrieve\"\n edges: [\"generate_rag\"]\n - name: \"generate_rag\"\n edges: [\"END\"]\n```\n\n资料来源：[README.md:70-85]()\n\n### 配置参数\n\n| 配置类别 | 参数名 | 说明 | 默认值 |\n|---------|-------|------|-------|\n| 历史记录 | `max_history` | 最大历史对话轮次 | 10 |\n| 重排序 | `supplier` | 重排序模型供应商 | cohere |\n| 重排序 | `model` | 重排序模型名称 | rerank-multilingual-v3.0 |\n| 重排序 | `top_n` | 返回的重排序结果数 | 5 |\n| LLM | `max_input_tokens` | 最大输入 token 数 | 4000 |\n| LLM | `temperature` | 生成温度参数 | 0.7 |\n\n资料来源：[README.md:85-100]()\n\n## 支持的文件格式\n\nQuivr 通过处理器架构支持多种文件格式：\n\n| 文件类型 | 支持状态 | 说明 |\n|---------|---------|------|\n| PDF | ✅ 完整支持 | 通过 Megaparse 集成 |\n| TXT | ✅ 完整支持 | 文本文件直接处理 |\n| Markdown | ✅ 完整支持 | 支持 Markdown 语法 |\n| 自定义 | ✅ 可扩展 | 支持添加自定义解析器 |\n\n资料来源：[README.md:35-40]()\n\n## 集成与扩展\n\n### 大语言模型集成\n\nQuivr 支持多种大语言模型供应商：\n\n| 供应商 | 支持状态 | 配置方式 |\n|-------|---------|---------|\n| OpenAI | ✅ 支持 | 设置 `OPENAI_API_KEY` |\n| Anthropic | ✅ 支持 | 设置 API Key |\n| Mistral | ✅ 支持 | 设置 API Key |\n| Ollama | ✅ 支持 | 本地模型配置 |\n| Gemma | ✅ 支持 | 通过 API 或本地部署 |\n\n资料来源：[README.md:20-25]()\n\n### 外部服务集成\n\n- **Megaparse**：用于大规模文件解析和 ingestion\n- **向量数据库**：支持可配置的向量存储后端\n\n资料来源：[README.md:38-42]()\n\n## 应用示例\n\n### 基础问答机器人\n\n使用 Chainlit 框架构建的文本问答机器人架构：\n\n```mermaid\ngraph TD\n A[用户上传文件] --> B[Chainlit 前端]\n B --> C[Quivr Brain 处理]\n C --> D[向量检索]\n D --> E[LLM 生成回答]\n E --> B\n```\n\n核心代码示例：\n\n```python\nfrom quivr_core import Brain\n\nbrain = Brain.from_files(\n name=\"my smart brain\",\n file_paths=[\"./my_first_doc.pdf\", \"./my_second_doc.txt\"],\n)\n\nanswer = brain.ask(question)\n```\n\n资料来源：[examples/simple_question/simple_question.py:1-20]()\n\n### 语音交互应用\n\nquivr-whisper 示例展示了如何构建语音交互系统：\n\n1. 用户录制语音问题\n2. 通过 Whisper 转录为文本\n3. 调用 Quivr API 获取回答\n4. 使用 TTS 将回答合成语音并播放\n\n资料来源：[examples/quivr-whisper/README.md:1-25]()\n\n## 项目结构\n\n```\nquivr/\n├── README.md # 主项目文档\n├── core/ # 核心包目录\n│ ├── README.md # quivr-core 说明\n│ └── quivr_core/\n│ ├── brain/ # Brain 核心类\n│ ├── rag/ # RAG 工作流\n│ ├── processor/ # 文件处理器\n│ └── llm/ # LLM 接口封装\n├── examples/ # 示例代码\n│ ├── chatbot/ # Chainlit 聊天机器人\n│ ├── chatbot_voice/ # 语音聊天机器人\n│ ├── simple_question/ # 简单问答示例\n│ └── pdf_parsing_tika.py # PDF 解析示例\n```\n\n资料来源：[core/README.md:1-15]()\n\n## 技术栈总结\n\n| 技术领域 | 使用的技术 |\n|---------|-----------|\n| 核心框架 | Python 3.10+ |\n| 向量检索 | 可配置向量数据库 |\n| 大语言模型 | OpenAI, Anthropic, Mistral, Ollama |\n| Web 框架 | Flask, Chainlit |\n| 语音处理 | Whisper |\n| 文件解析 | Megaparse |\n\n## 下一步\n\n- 访问 [官方文档](https://core.quivr.com/) 了解更多高级功能\n- 查看 [示例代码](./examples/) 学习具体用法\n- 参与 [贡献指南](https://github.com/QuivrHQ/quivr/blob/main/CONTRIBUTING.md) 加入社区\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [Brain 核心概念](#page-brain)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [examples/simple_question/simple_question.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question.py)\n- [examples/simple_question/simple_question_streaming.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question_streaming.py)\n- [examples/chatbot/main.py](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot/main.py)\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n- [core/README.md](https://github.com/QuivrHQ/quivr/blob/main/core/README.md)\n
\n\n# 快速入门指南\n\n## 概述\n\nQuivr-core 是 Quivr 项目的核心 RAG（检索增强生成）引擎，专注于让开发者能够快速构建基于文档的智能问答系统。本指南将帮助您从零开始，在 5 行代码内创建一个功能完整的 RAG 应用。\n\n## 安装\n\n使用 pip 安装 quivr-core 包：\n\n```bash\npip install quivr-core\n```\n\n资料来源：[core/README.md](https://github.com/QuivrHQ/quivr/blob/main/core/README.md)\n\n## 核心概念\n\n### Brain（大脑）\n\n`Brain` 是 Quivr-core 的核心类，负责管理文档处理、向量存储和问答逻辑。\n\n```mermaid\ngraph TD\n A[用户提问] --> B[Brain.ask]\n B --> C[检索相关文档]\n C --> D[构建提示词]\n D --> E[调用LLM]\n E --> F[返回答案]\n```\n\n## 基本用法\n\n### 创建 Brain 并提问\n\n以下示例演示了最基础的 RAG 用法：\n\n```python\nimport tempfile\nfrom quivr_core import Brain\n\nwith tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".txt\") as temp_file:\n temp_file.write(\"Gold is a liquid of blue-like colour.\")\n temp_file.flush()\n\n brain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[temp_file.name],\n )\n\n answer = brain.ask(\n question=\"what is gold? answer in french\",\n run_id=None # 需要传入UUID\n )\n print(\"answer:\", answer.answer)\n```\n\n资料来源：[examples/simple_question/simple_question.py:1-20](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question.py)\n\n### 异步提问方式\n\n`Brain.ask` 方法存在同步版本和异步版本：\n\n| 方法 | 描述 | 返回类型 |\n|------|------|----------|\n| `ask()` | 同步方法，等待完整回答 | `ParsedRAGResponse` |\n| `ask_streaming()` | 异步流式方法，逐块返回 | `AsyncGenerator[ParsedRAGChunkResponse]` |\n\n异步方法签名：\n\n```python\nasync def ask_streaming(\n self,\n run_id: UUID,\n question: str,\n system_prompt: str | None = None,\n retrieval_config: RetrievalConfig | None = None,\n rag_pipeline: Type[Union[QuivrQARAG, QuivrQARAGLangGraph]] | None = None,\n list_files: list[QuivrKnowledge] | None = None,\n chat_history: ChatHistory | None = None,\n) -> AsyncGenerator[ParsedRAGChunkResponse, None]\n```\n\n资料来源：[core/quivr_core/brain/brain.py:检索配置](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n\n### 流式响应示例\n\n```python\nimport asyncio\nfrom uuid import uuid4\n\nasync def streaming_example():\n brain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[\"./documents.pdf\"]\n )\n \n async for chunk in brain.ask_streaming(\n run_id=uuid4(),\n question=\"Summarize the document\"\n ):\n if not chunk.last_chunk:\n print(chunk.answer, end=\"\", flush=True)\n```\n\n## 环境配置\n\n### API Key 设置\n\n在使用 LLM 提供商之前，需要配置 API Key：\n\n```python\nimport os\nos.environ[\"OPENAI_API_KEY\"] = \"your-api-key-here\"\n```\n\nQuivr 支持的 LLM 提供商：\n\n| 提供商 | 环境变量 |\n|--------|----------|\n| OpenAI | `OPENAI_API_KEY` |\n| Anthropic | `ANTHROPIC_API_KEY` |\n| Mistral | `MISTRAL_API_KEY` |\n| Ollama（本地） | 需配置 `llm_base_url` |\n\n## 进阶配置\n\n### 自定义检索配置\n\n通过 `RetrievalConfig` 可以自定义检索行为：\n\n```python\nfrom quivr_core.config import RetrievalConfig\n\nconfig = RetrievalConfig(\n max_history=10,\n prompt=\"You are a helpful assistant.\",\n llm_config=LLMEndpointConfig(\n model=\"gpt-4\",\n temperature=0.7,\n max_input_tokens=4000\n )\n)\n\nanswer = brain.ask(\n run_id=uuid4(),\n question=\"your question\",\n retrieval_config=config\n)\n```\n\n### 使用 Chainlit 构建对话界面\n\n创建交互式聊天机器人的完整示例：\n\n```python\nimport chainlit as cl\nfrom uuid import uuid4\nfrom quivr_core import Brain\n\n@cl.on_message\nasync def main(message: cl.Message):\n # 获取或创建 brain\n brain = await cl.make_async(Brain.from_files)(\n name=\"chatbot_brain\",\n file_paths=[\"./data.txt\"]\n )\n \n msg = cl.Message(content=\"\")\n async for response in brain.ask_streaming(\n run_id=uuid4(),\n question=message.content\n ):\n if not response.last_chunk:\n await msg.stream_token(response.answer)\n \n await msg.send()\n```\n\n资料来源：[examples/chatbot/main.py](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot/main.py)\n\n## 工作流程\n\n```mermaid\ngraph LR\n A[文件] --> B[文件处理器]\n B --> C[文本分块]\n C --> D[向量化]\n D --> E[向量数据库]\n E --> F[检索]\n F --> G[LLM生成]\n G --> H[返回答案]\n```\n\n## 支持的文件格式\n\nQuivr-core 通过内置处理器支持多种文件格式：\n\n| 格式 | 处理器 |\n|------|--------|\n| PDF | `UnstructuredPDFLoader` |\n| TXT | `TextLoader` |\n| CSV | `CSVLoader` |\n| DOCX | `Docx2txtLoader` |\n| Markdown | `UnstructuredMarkdownLoader` |\n| HTML | `UnstructuredHTMLLoader` |\n| Excel | `UnstructuredExcelLoader` |\n| PowerPoint | `UnstructuredPowerPointLoader` |\n| Python | `PythonLoader` |\n\n## 下一步\n\n- 查看 [Workflow 配置文档](https://github.com/QuivrHQ/quivr/blob/main/README.md) 了解高级检索策略\n- 参考 [LangChain 集成](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py) 实现自定义处理流程\n- 探索 [语音聊天示例](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot_voice/README.md) 构建多模态应用\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[RAG 处理流程](#page-rag-flow), [Brain 核心概念](#page-brain)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/rag/quivr_rag_langgraph.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag_langgraph.py)\n- [core/quivr_core/config.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/config.py)\n- [core/quivr_core/storage/local_storage.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/local_storage.py)\n
\n\n# 系统架构\n\n## 概述\n\nQuivr 是一个基于生成式 AI 的个人第二大脑框架，其核心库 `quivr-core` 提供了一套完整的 RAG（检索增强生成）系统。该系统通过模块化设计，支持多种文件格式处理、灵活的 LLM 配置、可定制的检索策略以及持久化存储能力。资料来源：[README.md:1-30]()\n\n## 核心架构图\n\n```mermaid\ngraph TD\n subgraph 用户层\n A[用户查询] --> B[Brain.ask]\n end\n\n subgraph 核心层\n B --> C[RetrievalConfig]\n C --> D[QuivrQARAGLangGraph]\n D --> E[LLMEndpoint]\n D --> F[VectorStore]\n end\n\n subgraph 数据层\n F --> G[Chroma/FAISS/Pgvector]\n G --> H[Embeddings]\n end\n\n subgraph 存储层\n I[LocalStorage] --> J[Brain持久化]\n end\n\n style 用户层 fill:#e1f5fe\n style 核心层 fill:#fff3e0\n style 数据层 fill:#e8f5e9\n style 存储层 fill:#fce4ec\n```\n\n## 核心组件\n\n### Brain 类\n\n`Brain` 是整个系统的核心入口类，负责管理文件处理、向量存储、检索配置和 LLM 调用。资料来源：[core/quivr_core/brain/brain.py:1-100]()\n\n```mermaid\nclassDiagram\n class Brain {\n +id: UUID\n +name: str\n +llm: LLMEndpoint\n +embedder: Embeddings\n +vector_db: VectorStore\n +storage: StorageInterface\n +from_files()\n +afrom_files()\n +from_langchain_documents()\n +ask()\n +asearch()\n +save()\n +load()\n }\n```\n\n**Brain 核心属性表：**\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | `UUID` | 脑实例的唯一标识符 |\n| `name` | `str` | 脑实例的名称 |\n| `llm` | `LLMEndpoint` | 大语言模型端点 |\n| `embedder` | `Embeddings` | 嵌入模型用于向量化和检索 |\n| `vector_db` | `VectorStore` | 向量数据库实例 |\n| `storage` | `StorageInterface` | 文件存储接口 |\n\n资料来源：[core/quivr_core/brain/brain.py:50-60]()\n\n### RAG 引擎\n\nQuivr 提供两种 RAG 实现：基于 LangChain 的传统 RAG 和基于 LangGraph 的工作流 RAG。资料来源：[core/quivr_core/rag/quivr_rag.py:1-50]()\n\n```mermaid\ngraph LR\n A[用户问题] --> B[检索阶段]\n B --> C[重写查询]\n C --> D[历史过滤]\n D --> E[向量检索]\n E --> F[生成阶段]\n F --> G[LLM响应]\n```\n\n**QuivrQARAGLangGraph 工作流节点：**\n\n| 节点名称 | 功能 | 说明 |\n|----------|------|------|\n| `START` | 起点 | 工作流起始节点 |\n| `filter_history` | 历史过滤 | 过滤对话历史中的相关内容 |\n| `rewrite` | 查询重写 | 使用 LLM 优化用户查询 |\n| `generate` | 答案生成 | 基于检索结果生成最终答案 |\n\n资料来源：[core/quivr_core/rag/quivr_rag_langgraph.py:1-80]()\n\n### 配置系统\n\n配置系统通过 `RetrievalConfig` 类统一管理 RAG 流程的各个环节。资料来源：[core/quivr_core/config.py:1-100]()\n\n```python\nretrieval_config = RetrievalConfig.from_yaml(\"./basic_rag_workflow.yaml\")\n```\n\n**RetrievalConfig 核心参数：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `llm_config` | `LLMEndpointConfig` | 默认LLM | 语言模型配置 |\n| `temperature` | `float` | `0.7` | LLM 生成温度 |\n| `n_results` | `int` | `5` | 检索结果数量 |\n| `max_tokens` | `int` | `None` | 最大生成 token 数 |\n\n资料来源：[core/quivr_core/config.py:30-50]()\n\n## 数据流程\n\n### 文件处理流程\n\n```mermaid\ngraph TD\n A[文件上传] --> B[FileValidator]\n B --> C[FileProcessor]\n C --> D[LangChain Documents]\n D --> E[Embedder 向量化]\n E --> F[VectorStore 存储]\n F --> G[Brain 索引完成]\n```\n\n### 问答流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant B as Brain\n participant R as QuivrQARAGLangGraph\n participant V as VectorStore\n participant L as LLM\n\n U->>B: ask(question)\n B->>R: answer_astream()\n R->>V: asearch(query)\n V-->>R: 相关文档块\n R->>L: generate(上下文)\n L-->>R: 流式响应\n R-->>B: ParsedRAGChunkResponse\n B-->>U: 返回答案\n```\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:80-120]()\n\n## 存储系统\n\n### LocalStorage 实现\n\nLocalStorage 提供了本地文件系统存储能力，支持文件去重（基于 SHA-1 哈希）。资料来源：[core/quivr_core/storage/local_storage.py:1-80]()\n\n```mermaid\ngraph TD\n A[上传文件] --> B{计算SHA-1}\n B --> C{文件存在?}\n C -->|是| D{exists_ok?}\n C -->|否| E[复制/链接文件]\n D -->|True| E\n D -->|False| F[抛出FileExistsError]\n E --> G[更新文件列表]\n```\n\n**LocalStorage 核心方法：**\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `upload_file` | `file: QuivrFile, exists_ok: bool` | `None` | 上传文件到本地存储 |\n| `get_files` | 无 | `list[QuivrFile]` | 获取所有存储文件 |\n| `remove_file` | `file_id: UUID` | `None` | 移除指定文件 |\n| `load` | `config: LocalStorageConfig` | `Self` | 从配置加载存储实例 |\n\n资料来源：[core/quivr_core/storage/local_storage.py:50-70]()\n\n## 持久化与加载\n\n### Brain 保存与加载\n\nBrain 实例支持通过 `save()` 和 `load()` 方法进行持久化。资料来源：[examples/save_load_brain.py:1-25]()\n\n```python\n# 保存 Brain\nsave_path = await brain.save(\"/home/user/.local/quivr\")\n\n# 加载 Brain\nbrain_loaded = Brain.load(save_path)\n```\n\n**保存流程图：**\n\n```mermaid\ngraph LR\n A[Brain实例] --> B[序列化元数据]\n A --> C[序列化VectorDB]\n A --> D[序列化LLM配置]\n B --> E[写入文件系统]\n C --> E\n D --> E\n E --> F[返回保存路径]\n```\n\n## LLM 配置\n\nQuivr 支持多种 LLM 提供商，包括 OpenAI、Anthropic、Mistral 以及本地 Ollama 模型。资料来源：[core/quivr_core/llm/llm_endpoint.py:1-50]()\n\n```python\nfrom quivr_core.llm.llm_endpoint import LLMEndpoint\nfrom quivr_core.rag.entities.config import LLMEndpointConfig\n\nllm = LLMEndpoint.from_config(\n config=LLMEndpointConfig(\n model=\"gpt-4\",\n llm_base_url=\"https://api.openai.com/v1\",\n api_key=os.environ[\"OPENAI_API_KEY\"]\n )\n)\n```\n\n## 工作流配置\n\n通过 YAML 配置文件可以自定义 RAG 工作流节点和边。资料来源：[README.md:40-80]()\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"generate\"]\n - name: \"generate\"\n edges: []\n```\n\n## 模块依赖关系\n\n```mermaid\ngraph TD\n subgraph quivr_core\n A[Brain] --> B[RAG模块]\n A --> C[存储模块]\n A --> D[LLM模块]\n B --> E[配置模块]\n E --> F[向量存储]\n D --> F\n end\n\n subgraph 外部依赖\n G[LangChain]\n H[Chroma/FAISS]\n I[OpenAI API]\n end\n\n F --> H\n D --> G\n B --> G\n G --> I\n```\n\n## 关键设计决策\n\n| 设计点 | 说明 | 优势 |\n|--------|------|------|\n| 模块化 RAG | RAG 逻辑与 Brain 分离 | 便于测试和复用 |\n| LangGraph 工作流 | 使用状态图管理 RAG 流程 | 灵活的条件分支和并行处理 |\n| 异步优先 | 主要方法提供 async 版本 | 高并发场景性能优化 |\n| 向量存储抽象 | 统一 VectorStore 接口 | 支持多种后端切换 |\n| 配置驱动 | YAML 配置工作流 | 无需代码修改即可调整流程 |\n\n## 总结\n\nQuivr 的系统架构采用分层设计，核心层由 Brain 类统一调度，通过 RetrievalConfig 配置检索策略，借助 LangGraph 工作流实现灵活的 RAG 流程。向量存储层支持多种后端，存储层提供本地持久化能力，整体设计注重可扩展性和模块化，使开发者能够根据需求自由组合各组件。\n\n---\n\n\n\n## RAG 处理流程\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [LLM 集成](#page-llm)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/rag/quivr_rag_langgraph.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag_langgraph.py)\n- [core/quivr_core/rag/prompts.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/prompts.py)\n- [core/quivr_core/rag/entities/chat.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/chat.py)\n- [core/quivr_core/rag/entities/models.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/models.py)\n
\n\n# RAG 处理流程\n\n## 概述\n\nQuivr 的 RAG（检索增强生成）处理流程是核心功能模块，负责将用户查询与知识库中的文档相结合，生成准确、上下文相关的回答。该流程整合了文档检索、查询重写、历史过滤和流式响应生成等多个环节，形成一个完整的问答管道。\n\nRAG 流程的主要职责包括：从向量数据库中检索相关文档、对聊天历史进行过滤处理、将检索结果与用户查询组合成提示词、调用大语言模型生成回答，以及支持流式输出和元数据返回。资料来源：[core/quivr_core/rag/quivr_rag.py:1-50]()\n\n## 核心组件架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[用户查询] --> B[ChatHistory 聊天历史]\n B --> C[filter_history 过滤历史]\n C --> D[检索配置 RetrievalConfig]\n D --> E[向量存储 VectorStore]\n E --> F[Reranker 文档重排序]\n F --> G[LLMEndpoint 大语言模型]\n G --> H[流式响应 ParsedRAGChunkResponse]\n H --> I[最终回答]\n \n J[Brain 脑实例] --> E\n K[Embeddings 嵌入模型] --> E\n```\n\n### 核心类说明\n\n| 组件名称 | 文件位置 | 功能描述 |\n|---------|---------|---------|\n| `QuivrQARAG` | quivr_rag.py | RAG 主类，整合检索和生成流程 |\n| `IdempotentCompressor` | quivr_rag.py | 文档压缩器，保持原文档不变 |\n| `LLMEndpoint` | llm_endpoint.py | 大语言模型端点封装 |\n| `RetrievalConfig` | entities/config.py | 检索配置管理 |\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:44-60]()\n\n## 处理流程详解\n\n### 1. 聊天历史过滤\n\n在处理用户查询前，系统首先对聊天历史进行过滤，移除与当前问题无关的历史消息以提高检索效率。\n\n```python\ndef filter_history(\n self,\n chat_history: ChatHistory,\n):\n \"\"\"\n Filter out the chat history to only include the messages \n that are relevant to the current question\n \"\"\"\n```\n\n该方法接收 `ChatHistory` 对象作为输入，通过分析历史消息的相关性，返回过滤后的消息列表。资料来源：[core/quivr_core/rag/quivr_rag.py:68-76]()\n\n### 2. 文档检索配置\n\n检索配置定义了 RAG 流程的行为参数，包括：\n\n| 配置项 | 类型 | 说明 |\n|-------|------|-----|\n| `n_results` | int | 检索返回的结果数量，默认值为 5 |\n| `filter` | Callable/Dict | 检索过滤器条件 |\n| `fetch_n_neighbors` | int | 邻近检索数量，默认 20 |\n| `temperature` | float | LLM 温度参数，控制创造性 |\n\n资料来源：[core/quivr_core/brain/brain.py:80-95]()\n\n### 3. 向量存储检索\n\n`Brain` 类提供了 `asearch` 异步搜索方法，用于从向量数据库中检索相关文档：\n\n```python\nasync def asearch(\n self,\n query: str | Document,\n n_results: int = 5,\n filter: Callable | Dict[str, Any] | None = None,\n fetch_n_neighbors: int = 20,\n) -> list[SearchResult]:\n```\n\n该方法返回 `SearchResult` 对象列表，每个结果包含文档内容和元数据。资料来源：[core/quivr_core/brain/brain.py:80-95]()\n\n### 4. 提示词构建\n\n检索到的文档与用户查询一起被注入到提示词模板中：\n\n```python\nuser_prompt_template = \"\"\"\nHere is information about the user that can help you to answer:\n\n{user_metadata}\n\n\nHere are metadata on the current ticket:\n\n{ticket_metadata}\n\n\nHere are the most relevant similar tickets:\n\n{similar_tickets}\n\n\nHere is the client question:\n\n{client_query}\n\n\"\"\"\n```\n\n提示词模板支持以下占位符替换：\n\n- `{user_metadata}` - 用户元数据\n- `{ticket_metadata}` - 工单元数据\n- `{similar_tickets}` - 相似工单\n- `{ticket_history}` - 工单历史\n- `{additional_information}` - 附加信息\n- `{client_query}` - 客户端查询\n\n资料来源：[core/quivr_core/rag/prompts.py:1-50]()\n\n### 5. 流式响应生成\n\n`QuivrQARAG` 类实现了流式响应生成，通过 `answer_astream` 方法逐块返回 LLM 输出：\n\n```python\nasync def answer_astream(\n self,\n question: str,\n chat_history: ChatHistory,\n user_metadata: Dict[str, Any],\n # ... 其他参数\n) -> AsyncIterator[ParsedRAGChunkResponse]:\n```\n\n流式响应包含以下数据块结构：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `answer` | str | 当前块的文本内容 |\n| `metadata` | dict | 关联的来源文档信息 |\n| `last_chunk` | bool | 是否为最后一个数据块 |\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:20-45]()\n\n## 完整处理流程图\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant RAG as QuivrQARAG\n participant VS as VectorStore\n participant LLM as LLMEndpoint\n participant KB as 知识库\n\n U->>RAG: 发送查询问题\n RAG->>RAG: filter_history() 过滤历史\n \n alt 使用 LangGraph 工作流\n RAG->>RAG: rewrite_question() 重写问题\n RAG->>RAG: select_files() 选择文件\n RAG->>RAG: run_retrieval() 执行检索\n end\n \n RAG->>VS: 相似度搜索\n VS->>KB: 查询向量索引\n KB-->>VS: 返回相关文档\n VS-->>RAG: SearchResult 列表\n \n RAG->>RAG: compress_documents() 文档压缩\n RAG->>RAG: 构建提示词\n \n RAG->>LLM: 发送提示词\n LLM-->>RAG: 流式文本块\n \n loop 每个文本块\n RAG-->>U: ParsedRAGChunkResponse\n end\n \n RAG-->>U: 最终元数据块 (last_chunk=True)\n```\n\n## 文档处理管道\n\n在文档被摄入系统时，处理器会执行以下转换步骤：\n\n1. **文件解析** - 通过处理器提取文本内容\n2. **语言检测** - 使用 `detect_language` 函数识别文档语言\n3. **分块处理** - 将长文档分割为可管理的块\n4. **元数据增强** - 添加 chunk_index、quivr_core_version 等信息\n5. **UTF-8 规范化** - 处理特殊字符和编码问题\n\n```python\ndoc.metadata = {\n \"chunk_index\": idx,\n \"quivr_core_version\": qvr_version,\n \"language\": detect_language(\n text=doc.page_content.replace(\"\\\\n\", \" \").replace(\"\\n\", \" \"),\n low_memory=True,\n ).value,\n **file.metadata,\n **doc.metadata,\n **self.processor_metadata,\n}\n```\n\n资料来源：[core/quivr_core/processor/processor_base.py:1-30]()\n\n## 检索配置加载\n\n支持从 YAML 配置文件加载检索配置：\n\n```python\nretrieval_config = RetrievalConfig.from_yaml(config_file_name)\n```\n\n配置示例：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"llm\"]\n temperature: 0.7\n```\n\n资料来源：[README.md:30-60]()\n\n## 使用示例\n\n### 基础 RAG 问答\n\n```python\nfrom quivr_core import Brain\n\nbrain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[\"./document.pdf\"],\n)\n\nanswer = brain.ask(\"文档的主要内容是什么？\")\nprint(answer.answer)\n```\n\n### 自定义检索配置\n\n```python\nfrom quivr_core.config import RetrievalConfig\n\nconfig = RetrievalConfig.from_yaml(\"./basic_rag_workflow.yaml\")\nanswer = brain.ask(\n \"问题内容\",\n retrieval_config=config\n)\n```\n\n## 总结\n\nQuivr 的 RAG 处理流程通过模块化设计实现了高效的检索增强生成能力。核心流程包括聊天历史过滤、向量检索、文档重排序、提示词构建和大语言模型生成，最终通过流式接口返回响应结果。该架构支持灵活的配置和扩展，能够适应不同的应用场景需求。\n\n---\n\n\n\n## Brain 核心概念\n\n### 相关页面\n\n相关主题：[存储系统](#page-storage), [文件处理系统](#page-processor)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n- [core/quivr_core/storage/local_storage.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/local_storage.py)\n- [examples/simple_question/simple_question.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question.py)\n- [examples/save_load_brain.py](https://github.com/QuivrHQ/quivr/blob/main/examples/save_load_brain.py)\n- [examples/pdf_parsing_tika.py](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py)\n
\n\n# Brain 核心概念\n\n## 概述\n\nBrain（大脑）是 Quivr 项目的核心抽象概念，它代表了一个基于生成式 AI 的个人知识库助手系统。Brain 将文档处理、向量存储检索和大语言模型问答有机结合，为用户提供与私有文档进行自然语言交互的能力。\n\nQuivr 的 Brain 采用 RAG（检索增强生成）架构，支持多种文件类型、多种 LLM 提供商，并允许用户通过 YAML 配置文件自定义检索策略和工作流程。\n\n## 核心组件\n\n### Brain 类\n\n`Brain` 类是整个系统的核心，位于 `core/quivr_core/brain/brain.py`。它封装了大脑的所有功能：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 大脑唯一标识符 |\n| `name` | str | 大脑名称 |\n| `storage` | BrainStorage | 文件存储后端 |\n| `llm` | LLMEndpoint | 大语言模型接口 |\n| `embedder` | Embeddings | 文档嵌入模型 |\n| `vector_db` | VectorDBInput | 向量数据库 |\n\n### 创建 Brain\n\n#### 从文件创建\n\n```python\nfrom quivr_core import Brain\n\nbrain = Brain.from_files(\n name=\"my_smart_brain\",\n file_paths=[\"./my_first_doc.pdf\", \"./my_second_doc.txt\"],\n)\n```\n\n#### 异步创建\n\n```python\nbrain = await Brain.afrom_files(\n name=\"test_brain\",\n file_paths=[temp_file.name]\n)\n```\n\n#### 从 LangChain 文档创建\n\n```python\nfrom langchain_core.documents import Document\nfrom quivr_core import Brain\n\ndocuments = [Document(page_content=\"Hello, world!\")]\nbrain = await Brain.afrom_langchain_documents(\n name=\"My Brain\",\n langchain_documents=documents\n)\n```\n\n## 核心功能\n\n### 问答功能 (ask)\n\nBrain 的主要功能是回答用户关于已加载文档的问题：\n\n```python\nanswer = brain.ask(\"what is gold? answer in french\")\nprint(\"answer:\", answer)\n```\n\n问答流程如下：\n\n```mermaid\ngraph TD\n A[用户问题] --> B[检索配置解析]\n B --> C{是否指定LLM}\n C -->|是| D[使用指定LLM]\n C -->|否| E[使用Brain默认LLM]\n D --> F[创建QuivrQARAGLangGraph]\n E --> F\n F --> G[向量数据库检索相关文档]\n G --> H[构建聊天历史]\n H --> I[调用LLM生成答案]\n I --> J[返回Answer对象]\n```\n\n### 异步流式问答 (ask_streaming)\n\n支持流式输出，适合实时展示生成过程：\n\n```python\nasync for chunk in brain.ask_streaming(\"What is the meaning of life?\"):\n print(chunk.answer)\n```\n\n### 文档检索 (asearch)\n\n直接检索向量数据库中的相关文档块：\n\n```python\nresults = await brain.asearch(\n query=\"查询文本\",\n n_results=5,\n fetch_n_neighbors=20\n)\n```\n\n## 数据模型\n\n### Answer 对象\n\n`ask()` 方法返回 `Answer` 对象，包含：\n\n- `answer`: 生成的答案文本\n- `sources`: 答案来源的文档块\n- `metadata`: 额外的元数据信息\n\n### SearchResult 对象\n\n`asearch()` 方法返回 `SearchResult` 列表，每个结果包含：\n\n- `content`: 文档内容\n- `metadata`: 文档元数据\n- `score`: 相关性分数\n\n## 配置管理\n\n### RetrievalConfig\n\n检索配置控制 RAG 工作流的行为：\n\n```python\nfrom quivr_core.config import RetrievalConfig\n\nretrieval_config = RetrievalConfig.from_yaml(config_file_name)\n\nanswer = brain.ask(\n question,\n retrieval_config=retrieval_config\n)\n```\n\n### YAML 工作流配置\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"retrieval\"]\n```\n\n## 持久化与加载\n\n### 保存 Brain\n\n```python\nsave_path = await brain.save(\"/home/user/.local/quivr\")\n```\n\n保存机制使用 SHA-1 哈希检测重复文件，避免存储冗余：\n\n```python\n# 资料来源：core/quivr_core/storage/local_storage.py:45-52\nif file.file_sha1 in self.hashes and not exists_ok:\n raise FileExistsError(f\"file {file.original_filename} already uploaded\")\n```\n\n### 加载 Brain\n\n```python\nbrain_loaded = Brain.load(save_path)\nbrain_loaded.print_info()\n```\n\n## 高级配置\n\n### 自定义 LLM\n\n```python\nfrom quivr_core.rag.entities.config import LLMEndpointConfig\nfrom quivr_core.llm.llm_endpoint import LLMEndpoint\nfrom langchain_core.language_models import FakeListChatModel\n\nbrain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[\"tests/processor/data/dummy.pdf\"],\n llm=LLMEndpoint(\n llm=FakeListChatModel(responses=[\"good\"]),\n llm_config=LLMEndpointConfig(model=\"fake_model\", llm_base_url=\"local\"),\n ),\n embedder=DeterministicFakeEmbedding(size=20),\n)\n```\n\n### 自定义解析器\n\n```python\nprocessor_kwargs = {\n \"megaparse_config\": megaparse_config,\n \"splitter_config\": assistant_config.ingestion_config.parser_config.splitter_config,\n}\n\nbrain = await Brain.afrom_files(\n name=\"test_brain\",\n file_paths=file_path,\n processor_kwargs=processor_kwargs,\n)\n```\n\n## 支持的文件类型\n\nQuivr Brain 支持处理多种文件类型：\n\n- PDF 文档\n- TXT 文本文件\n- Markdown 文件\n- 支持自定义解析器扩展\n\n## 信息查看\n\n查看 Brain 的详细信息：\n\n```python\nbrain.print_info()\n```\n\n## 系统架构图\n\n```mermaid\ngraph TB\n subgraph \"用户层\"\n A[用户提问]\n B[流式输出]\n end\n \n subgraph \"Brain 核心\"\n C[Brain.ask]\n D[RetrievalConfig]\n E[QuivrQARAGLangGraph]\n F[RAG 工作流]\n end\n \n subgraph \"检索层\"\n G[向量数据库]\n H[嵌入模型]\n I[元数据过滤]\n end\n \n subgraph \"生成层\"\n J[LLM Endpoint]\n K[聊天历史]\n L[系统提示词]\n end\n \n A --> C\n C --> D\n D --> E\n E --> F\n F --> G\n F --> H\n F --> I\n F --> J\n J --> B\n```\n\n## 最佳实践\n\n1. **选择合适的嵌入模型**：嵌入模型直接影响检索质量\n2. **配置检索参数**：根据文档复杂度调整 `n_results` 和 `fetch_n_neighbors`\n3. **使用 YAML 配置**：通过配置文件管理复杂的工作流，便于调整和版本控制\n4. **异步处理大文件**：使用 `afrom_files()` 和 `ask_streaming()` 提升性能\n\n---\n\n\n\n## 文件处理系统\n\n### 相关页面\n\n相关主题：[Brain 核心概念](#page-brain), [存储系统](#page-storage)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/processor/processor_base.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/processor_base.py)\n- [core/quivr_core/processor/registry.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/registry.py)\n- [core/quivr_core/processor/splitter.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/splitter.py)\n- [core/quivr_core/processor/implementations/default.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/implementations/default.py)\n- [core/quivr_core/processor/implementations/megaparse_processor.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/implementations/megaparse_processor.py)\n- [core/quivr_core/processor/implementations/tika_processor.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/implementations/tika_processor.py)\n- [examples/pdf_parsing_tika.py](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py)\n- [examples/simple_question_megaparse.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question_megaparse.py)\n
\n\n# 文件处理系统\n\n## 概述\n\nQuivr 的文件处理系统是构建检索增强生成（RAG）工作流的核心组件，负责将各种格式的文档转换为可供大语言模型（LLM）处理的文本块（chunks）。该系统采用插件化架构，通过处理器注册表动态加载和支持多种文件类型，支持包括 PDF、Word、文本、CSV、HTML、Markdown 等常见文档格式。\n\n系统的设计目标是将非结构化文档内容标准化为统一的 `Document` 对象格式，同时通过文本分割器将长文档切分为适合嵌入和检索的语义块。这一处理流程确保了后续的向量数据库索引和问答系统能够高效准确地工作。\n\n## 核心架构\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[QuivrFile] --> B[ProcessorRegistry]\n B --> C[ProcessorBase]\n C --> D[process_file]\n D --> E[process_file_inner]\n E --> F[ProcessedDocument]\n F --> G[Document Chunks]\n G --> H[向量数据库]\n I[Language Detection] --> F\n J[Metadata Enrichment] --> F\n```\n\n### 处理流程\n\n文件处理的核心流程包含以下步骤：\n\n1. **文件验证**：检查文件扩展名是否在支持列表中\n2. **内容提取**：调用具体处理器的 `process_file_inner` 方法提取文本\n3. **语言检测**：使用 `detect_language` 函数自动识别文档语言\n4. **元数据丰富**：添加处理版本、块索引、语言标识等元数据\n5. **文本分割**：按配置的 `SplitterConfig` 将文档分割为块\n6. **格式标准化**：处理 Unicode 特殊字符和编码问题\n\n## ProcessorBase 基类\n\n### 类定义与接口\n\n`ProcessorBase` 是所有文件处理器的抽象基类，定义在 `processor_base.py` 中：\n\n```python\nclass ProcessorBase(ABC, Generic[R]):\n supported_extensions: list[FileExtension | str]\n \n @property\n @abstractmethod\n def processor_metadata(self) -> dict[str, Any]:\n raise NotImplementedError\n \n async def process_file(self, file: QuivrFile) -> ProcessedDocument[R]:\n # 处理逻辑\n```\n\n### ProcessedDocument 数据结构\n\n处理器返回的 `ProcessedDocument` 包含三个核心字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `chunks` | `List[Document]` | 分割后的文档块列表 |\n| `processor_cls` | `str` | 处理器类名标识 |\n| `processor_response` | `R` | 处理器特定响应数据 |\n\n### 元数据处理逻辑\n\n处理过程中会自动丰富每个文档块的元数据：\n\n```python\ndoc.metadata = {\n \"chunk_index\": idx, # 块在文档中的位置\n \"quivr_core_version\": qvr_version, # 版本信息\n \"language\": detect_language(...).value, # 检测到的语言\n **file.metadata, # 文件原始元数据\n **doc.metadata, # 文档自身元数据\n **self.processor_metadata, # 处理器特定元数据\n}\n```\n\n资料来源：[processor_base.py:30-50](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/processor_base.py)\n\n## 处理器注册表\n\n### 注册机制\n\n`registry.py` 实现了动态处理器加载机制，支持按优先级回退：\n\n```python\ndef fetch_processor_class(file_extension: FileExtension) -> Type[ProcessorBase]:\n if file_extension not in registry:\n entries = known_processors[file_extension]\n while entries:\n proc_entry = heappop(entries)\n try:\n register_processor(file_extension, _import_class(proc_entry.cls_mod))\n break\n except ImportError:\n logger.warn(f\"{proc_entry.err}. Falling to next...\")\n```\n\n### 优先级回退策略\n\n当某个处理器因缺少依赖无法加载时，系统自动尝试下一个候选处理器：\n\n| 优先级 | 处理器类型 | 依赖要求 |\n|--------|------------|----------|\n| 高 | MegaparseProcessor | megaparse 包 |\n| 中 | TikaProcessor | Apache Tika |\n| 低 | DefaultProcessor | langchain 加载器 |\n\n资料来源：[registry.py:30-55](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/registry.py)\n\n## 文本分割器配置\n\n### SplitterConfig 配置项\n\n分割器通过 `SplitterConfig` 数据类配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `chunk_size` | `int` | 500 | 每个块的字符数 |\n| `chunk_overlap` | `int` | 0 | 块之间的重叠字符数 |\n| `splitter_name` | `str` | \"RecursiveCharacter\" | 分割器类型 |\n\n资料来源：[splitter.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/splitter.py)\n\n### 分割器实现\n\nQuivr 使用 LangChain 的 `RecursiveCharacterTextSplitter` 作为默认分割器，该分割器按优先级尝试按不同分隔符分割文本，确保语义完整性。\n\n## 处理器实现\n\n### DefaultProcessor\n\n默认处理器基于 LangChain 社区的文档加载器构建，支持多种格式：\n\n| 文件类型 | LangChain 加载器 |\n|----------|------------------|\n| PDF | `UnstructuredPDFLoader` |\n| Word | `Docx2txtLoader` |\n| CSV | `CSVLoader` |\n| HTML | `UnstructuredHTMLLoader` |\n| Markdown | `UnstructuredMarkdownLoader` |\n| Excel | `UnstructuredExcelLoader` |\n| PowerPoint | `UnstructuredPowerPointLoader` |\n\n处理器类通过动态工厂模式构建，每个类包含支持的扩展名列表和对应的分割器配置。\n\n资料来源：[implementations/default.py:15-35](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/implementations/default.py)\n\n### TikaProcessor\n\nTika 处理器基于 Apache Tika 引擎，提供更强大的 PDF 解析能力：\n\n```python\nclass TikaProcessor(ProcessorBase):\n supported_extensions = [FileExtension.pdf]\n```\n\nTika 能够提取 PDF 的文本内容、元数据并处理复杂的文档结构。\n\n### MegaparseProcessor\n\nMegaparse 处理器是 Quivr 官方开发的高性能解析器，针对大规模文档处理优化：\n\n```python\nclass MegaparseProcessor(ProcessorBase):\n supported_extensions = [FileExtension.pdf, FileExtension.txt]\n \n @property\n def processor_metadata(self) -> dict[str, Any]:\n return {\n \"processor_cls\": \"MegaparseProcessor\",\n \"parser\": \"megaparse\",\n }\n```\n\n## 使用示例\n\n### 基本用法\n\n使用 `Brain.from_files` 方法时，系统自动选择合适的处理器：\n\n```python\nfrom quivr_core import Brain\n\nbrain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[\"./document.pdf\", \"./notes.txt\"],\n)\nanswer = brain.ask(\"What is the main topic?\")\n```\n\n### 指定 Tika 处理器解析 PDF\n\n```python\nfrom langchain_core.embeddings import DeterministicFakeEmbedding\nfrom langchain_core.language_models import FakeListChatModel\nfrom quivr_core import Brain\nfrom quivr_core.rag.entities.config import LLMEndpointConfig\nfrom quivr_core.llm.llm_endpoint import LLMEndpoint\nfrom quivr_core.processor.implementations.tika_processor import TikaProcessor\n\nbrain = Brain.from_files(\n name=\"pdf_brain\",\n file_paths=[\"document.pdf\"],\n processor=TikaProcessor(),\n llm=LLMEndpoint(\n llm=FakeListChatModel(responses=[\"good\"]),\n llm_config=LLMEndpointConfig(model=\"fake_model\", llm_base_url=\"local\"),\n ),\n embedder=DeterministicFakeEmbedding(size=20),\n)\n```\n\n资料来源：[examples/pdf_parsing_tika.py](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py)\n\n### 指定 Megaparse 处理器\n\n```python\nfrom quivr_core import Brain\nfrom quivr_core.processor.implementations megaparse_processor import MegaparseProcessor\n\nbrain = Brain.from_files(\n name=\"megaparse_brain\",\n file_paths=[\"document.pdf\"],\n processor=MegaparseProcessor(),\n)\n```\n\n## 扩展自定义处理器\n\n### 实现步骤\n\n1. 继承 `ProcessorBase` 基类\n2. 定义 `supported_extensions` 列表\n3. 实现 `process_file_inner` 异步方法\n4. 实现 `processor_metadata` 属性\n\n### 示例代码\n\n```python\nfrom quivr_core.processor.processor_base import ProcessedDocument, ProcessorBase\nfrom quivr_core.files.file import QuivrFile\nfrom langchain_core.documents import Document\n\nclass CustomProcessor(ProcessorBase):\n supported_extensions = [\".custom\"]\n \n @property\n def processor_metadata(self) -> dict[str, Any]:\n return {\"processor_cls\": \"CustomProcessor\"}\n \n async def process_file_inner(self, file: QuivrFile) -> ProcessedDocument[str]:\n # 实现自定义解析逻辑\n content = await self.extract_content(file)\n return ProcessedDocument(\n chunks=[Document(page_content=content, metadata={})],\n processor_cls=\"CustomProcessor\",\n processor_response=content,\n )\n```\n\n## 错误处理\n\n### 常见错误类型\n\n| 错误类型 | 原因 | 处理方式 |\n|----------|------|----------|\n| `ValueError` | 不支持的文件扩展名 | 检查 `supported_extensions` |\n| `ImportError` | 缺少处理器依赖 | 安装相应依赖或使用回退处理器 |\n\n### 验证机制\n\n处理器在执行前会验证文件类型：\n\n```python\ndef check_supported(self, file: QuivrFile) -> None:\n if file.file_extension not in self.supported_extensions:\n raise ValueError(f\"can't process a file of type {file.file_extension}\")\n```\n\n资料来源：[processor_base.py:35-38](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/processor_base.py)\n\n## 总结\n\nQuivr 的文件处理系统通过模块化设计和动态加载机制，提供了灵活且可扩展的文档处理能力。处理器注册表配合优先级回退策略确保了系统的鲁棒性，而统一的 `ProcessedDocument` 接口使得不同处理器的输出可以被后续组件无缝使用。开发者可以通过实现 `ProcessorBase` 接口轻松添加新的文件格式支持。\n\n---\n\n\n\n## 存储系统\n\n### 相关页面\n\n相关主题：[Brain 核心概念](#page-brain), [文件处理系统](#page-processor)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/storage/storage_base.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/storage_base.py)\n- [core/quivr_core/storage/local_storage.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/local_storage.py)\n- [core/quivr_core/storage/file.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/file.py)\n- [examples/custom_storage.md](https://github.com/QuivrHQ/quivr/blob/main/examples/custom_storage.md)\n
\n\n# 存储系统\n\n## 概述\n\nQuivr 的存储系统是整个 RAG（检索增强生成）框架的核心组件之一，负责管理文件的存取、元数据管理以及文件到向量数据库的转换流程。存储系统采用了抽象基类设计模式，支持本地存储和透明存储两种实现方式，同时允许开发者通过实现 `StorageBase` 接口来创建自定义存储后端。\n\n存储系统的主要职责包括：\n\n- 文件的读取与写入操作\n- 文件元数据的提取与管理（包括文件大小、SHA1 哈希值、文件扩展名等）\n- 支持异步文件操作以提高性能\n- 为处理器提供统一的文件访问接口\n\n资料来源：[core/quivr_core/brain/brain.py](core/quivr_core/brain/brain.py)\n\n## 核心架构\n\n### 存储系统类层次结构\n\n```mermaid\ngraph TD\n A[StorageBase] --> B[LocalStorage]\n A --> C[TransparentStorage]\n A --> D[Custom Storage]\n \n E[QuivrFile] --> F[文件元数据]\n G[process_files] --> A\n H[Brain] --> G\n```\n\n### 核心组件\n\n| 组件 | 类型 | 职责 |\n|------|------|------|\n| `StorageBase` | 抽象基类 | 定义存储系统接口规范 |\n| `LocalStorage` | 具体实现 | 本地文件系统存储 |\n| `TransparentStorage` | 具体实现 | 透明存储包装器 |\n| `QuivrFile` | 数据类 | 文件元数据与路径管理 |\n\n资料来源：[core/quivr_core/storage/storage_base.py](core/quivr_core/storage/storage_base.py)\n\n## StorageBase 抽象基类\n\n`StorageBase` 是所有存储实现的基类，定义了存储系统的核心接口规范。\n\n### 主要接口方法\n\n| 方法名 | 返回类型 | 说明 |\n|--------|----------|------|\n| `get_files()` | `AsyncGenerator[QuivrFile]` | 异步获取存储中的所有文件 |\n| `add_file()` | `None` | 添加文件到存储 |\n| `get_file_by_id()` | `QuivrFile` | 根据 ID 获取文件 |\n\n### 抽象方法定义\n\n```python\nclass StorageBase(ABC):\n @abstractmethod\n async def get_files(self) -> AsyncGenerator[QuivrFile, None]:\n raise NotImplementedError\n \n @abstractmethod\n async def add_file(self, file: QuivrFile) -> None:\n raise NotImplementedError\n```\n\n资料来源：[core/quivr_core/storage/storage_base.py](core/quivr_core/storage/storage_base.py)\n\n## QuivrFile 文件元数据类\n\n`QuivrFile` 是用于表示存储中文件的数据类，使用 `__slots__` 优化内存占用。\n\n### 数据结构\n\n```python\nclass QuivrFile:\n __slots__ = [\n \"id\", # UUID 文件唯一标识\n \"brain_id\", # UUID 所属脑部ID\n \"path\", # Path 文件路径\n \"original_filename\", # str 原始文件名\n \"file_size\", # int 文件大小\n \"file_extension\", # FileExtension 文件扩展名\n \"file_sha1\", # str SHA1哈希值\n \"additional_metadata\", # dict 额外元数据\n ]\n```\n\n### 构造函数参数\n\n| 参数名 | 类型 | 必需 | 说明 |\n|--------|------|------|------|\n| `id` | `UUID` | 是 | 文件唯一标识符 |\n| `original_filename` | `str` | 是 | 文件原始名称 |\n| `path` | `Path` | 是 | 文件存储路径 |\n| `file_sha1` | `str` | 是 | 文件 SHA1 哈希值 |\n| `file_extension` | `FileExtension \\| str` | 是 | 文件扩展名 |\n| `brain_id` | `UUID \\| None` | 否 | 关联的脑部 ID |\n| `file_size` | `int \\| None` | 否 | 文件大小（字节） |\n| `metadata` | `dict \\| None` | 否 | 额外元数据字典 |\n\n资料来源：[core/quivr_core/files/file.py](core/quivr_core/files/file.py)\n\n### 异步文件打开\n\n`QuivrFile` 提供了异步上下文管理器用于安全地打开文件：\n\n```python\n@asynccontextmanager\nasync def open(self) -> AsyncGenerator[AsyncIterable[bytes], None]:\n f = await aiofiles.open(self.path, mode=\"rb\")\n try:\n yield f\n finally:\n await f.close()\n```\n\n资料来源：[core/quivr_core/files/file.py](core/quivr_core/files/file.py)\n\n## LocalStorage 本地存储实现\n\n`LocalStorage` 是基于本地文件系统的存储实现，适用于单节点部署场景。\n\n### 文件处理流程\n\n```mermaid\ngraph TD\n A[开始处理] --> B{文件是否存在}\n B -->|不存在| C[抛出 ValueError]\n B -->|存在| D[提取文件扩展名]\n D --> E[计算 SHA1 哈希]\n E --> F[计算文件大小]\n F --> G[创建 QuivrFile 对象]\n G --> H[添加到文件列表]\n H --> I[返回 QuivrFile]\n```\n\n### 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 批量文件加载 | 从指定目录加载所有支持的文件 |\n| 元数据自动提取 | 自动计算文件哈希和大小 |\n| 文件扩展名识别 | 识别并返回文件类型 |\n\n资料来源：[core/quivr_core/storage/local_storage.py](core/quivr_core/storage/local_storage.py)\n\n## TransparentStorage 透明存储\n\n`TransparentStorage` 是一个存储包装器，用于在不改变现有接口的情况下扩展存储功能。\n\n### 使用场景\n\n- 日志记录：透明地记录所有存储操作\n- 缓存层：在存储操作前后添加缓存逻辑\n- 访问控制：添加权限检查逻辑\n\n资料来源：[core/quivr_core/rag/quivr_rag_langgraph.py](core/quivr_core/rag/quivr_rag_langgraph.py)\n\n## 文件处理集成\n\n存储系统与处理器系统紧密集成，形成完整的文件处理流水线：\n\n```mermaid\ngraph LR\n A[StorageBase] -->|get_files| B[process_files]\n B -->|QuivrFile| C[get_processor_class]\n C -->|ProcessorBase| D[process_file]\n D -->|Document| E[向量数据库]\n```\n\n### 异步处理流程\n\n```python\nasync def process_files(\n storage: StorageBase, \n skip_file_error: bool, \n **processor_kwargs: dict[str, Any]\n) -> list[Document]:\n```\n\n处理流程说明：\n\n1. 遍历存储中的所有文件\n2. 根据文件扩展名获取对应的处理器\n3. 调用处理器提取文档内容\n4. 返回 LangChain Document 列表\n\n资料来源：[core/quivr_core/brain/brain.py](core/quivr_core/brain/brain.py)\n\n## 自定义存储实现\n\n开发者可以通过继承 `StorageBase` 来实现自定义存储后端。\n\n### 实现步骤\n\n1. 创建继承自 `StorageBase` 的新类\n2. 实现 `get_files()` 异步生成器方法\n3. 实现 `add_file()` 异步方法\n4. 在 Brain 初始化时传入自定义存储实例\n\n### 示例结构\n\n```python\nclass CustomStorage(StorageBase):\n async def get_files(self) -> AsyncGenerator[QuivrFile, None]:\n # 实现自定义文件获取逻辑\n ...\n \n async def add_file(self, file: QuivrFile) -> None:\n # 实现自定义文件添加逻辑\n ...\n```\n\n资料来源：[examples/custom_storage.md](https://github.com/QuivrHQ/quivr/blob/main/examples/custom_storage.md)\n\n## 配置与使用\n\n### 在 Brain 中使用存储\n\n```python\nfrom quivr_core import Brain\nfrom quivr_core.storage.local_storage import LocalStorage\n\n# 使用默认本地存储\nbrain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[\"./documents/\"]\n)\n\n# 使用自定义存储\nbrain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[],\n storage=CustomStorage(...)\n)\n```\n\n资料来源：[README.md](README.md)\n\n## 最佳实践\n\n### 性能优化\n\n| 实践 | 说明 |\n|------|------|\n| 异步操作 | 所有文件 I/O 操作均使用异步方式 |\n| 内存效率 | 使用 `__slots__` 减少对象内存占用 |\n| 错误处理 | 支持 `skip_file_error` 参数跳过无法处理的文件 |\n\n### 错误处理\n\n存储系统在处理文件时会进行多种校验：\n\n- 文件扩展名识别\n- 文件 SHA1 哈希计算\n- 文件大小统计\n- 路径有效性验证\n\n资料来源：[core/quivr_core/files/file.py](core/quivr_core/files/file.py)\n\n## 总结\n\nQuivr 的存储系统采用模块化设计，通过抽象基类 `StorageBase` 提供了灵活的可扩展性。开发者可以根据实际需求选择本地存储、透明存储或实现自定义存储后端。存储系统与处理器系统的紧密集成使得文件到向量数据库的转换过程透明且高效。\n\n---\n\n\n\n## LLM 集成\n\n### 相关页面\n\n相关主题：[RAG 处理流程](#page-rag-flow), [工具扩展系统](#page-tools)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/llm/llm_endpoint.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/llm/llm_endpoint.py)\n- [core/quivr_core/rag/entities/config.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/config.py)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/rag/quivr_rag_langgraph.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag_langgraph.py)\n- [core/quivr_core/rag/entities/models.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/models.py)\n- [core/quivr_core/rag/prompts.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/prompts.py)\n
\n\n# LLM 集成\n\nQuivr 的 LLM 集成模块是整个 RAG（检索增强生成）系统的核心组件，负责与大语言模型交互以生成智能回答。本模块提供了灵活的 LLM 端点配置、支持多种模型提供商，并深度集成了 LangChain 生态系统。\n\n## 架构概述\n\nQuivr 的 LLM 集成采用分层架构设计，通过 `LLMEndpoint` 类封装底层模型调用，提供统一的接口供 RAG 工作流使用。\n\n```mermaid\ngraph TD\n subgraph \"LLM 集成层\"\n A[LLMEndpoint] --> B[LLMEndpointConfig]\n A --> C[BaseChatModel]\n end\n \n subgraph \"RAG 工作流\"\n D[QuivrRAG] --> A\n E[QuivrRAGLangGraph] --> A\n end\n \n subgraph \"模型提供商\"\n F[OpenAI] --> A\n G[Anthropic] --> A\n H[Mistral] --> A\n I[Ollama 本地模型] --> A\n end\n```\n\n## 核心组件\n\n### LLMEndpoint\n\n`LLMEndpoint` 是 LLM 集成的核心类，位于 `core/quivr_core/llm/llm_endpoint.py`。它封装了 LangChain 的聊天模型，提供配置管理和调用接口。\n\n```python\nfrom quivr_core.llm.llm_endpoint import LLMEndpoint\nfrom quivr_core.rag.entities.config import LLMEndpointConfig\n\nllm = LLMEndpoint(\n llm=chat_model_instance,\n llm_config=LLMEndpointConfig(\n model=\"gpt-4\",\n temperature=0.7,\n max_tokens=2000\n )\n)\n```\n\n### LLMEndpointConfig 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `str` | 必需 | 模型标识符，如 \"gpt-4\"、\"claude-3\" |\n| `temperature` | `float` | `0.7` | 生成温度，控制随机性 |\n| `max_tokens` | `int` | `2000` | 最大生成 token 数 |\n| `llm_base_url` | `str` | `None` | API 基础 URL（用于代理或自定义端点） |\n| `streaming` | `bool` | `True` | 是否启用流式输出 |\n\n资料来源：[core/quivr_core/rag/entities/config.py:1-100]()\n\n## 配置管理\n\n### 默认 LLM 配置\n\nQuivr 提供了默认 LLM 工厂函数，简化常见场景下的配置：\n\n```python\nfrom quivr_core.llm import default_llm\n\n# 使用默认配置创建 LLM\nllm = default_llm()\n```\n\n### 环境变量配置\n\nLLM 集成支持通过环境变量配置 API 密钥：\n\n```python\nimport os\nos.environ[\"OPENAI_API_KEY\"] = \"your-api-key\"\nos.environ[\"ANTHROPIC_API_KEY\"] = \"your-anthropic-key\"\nos.environ[\"MISTRAL_API_KEY\"] = \"your-mistral-key\"\n```\n\n## 模型支持\n\nQuivr 的 LLM 集成支持多种模型提供商：\n\n### 支持的提供商\n\n| 提供商 | 模型示例 | 配置方式 |\n|--------|----------|----------|\n| OpenAI | GPT-4, GPT-3.5-turbo | `OPENAI_API_KEY` |\n| Anthropic | Claude-3 Opus, Claude-3 Sonnet | `ANTHROPIC_API_KEY` |\n| Mistral | Mistral Large, Mistral Medium | `MISTRAL_API_KEY` |\n| Ollama | 本地部署的开源模型 | 本地 URL 配置 |\n\n### 本地模型支持（Ollama）\n\nQuivr 支持使用 Ollama 运行本地大语言模型：\n\n```python\nfrom langchain_ollama import ChatOllama\n\nllm = ChatOllama(\n model=\"llama2\",\n base_url=\"http://localhost:11434\"\n)\n\nconfig = LLMEndpointConfig(\n model=\"llama2\",\n llm_base_url=\"http://localhost:11434\"\n)\n\nendpoint = LLMEndpoint(llm=llm, llm_config=config)\n```\n\n## RAG 中的 LLM 集成\n\n### QuivrRAG 类\n\n`QuivrRAG` 类是核心 RAG 实现，通过 LLMEndpoint 进行问答生成：\n\n```mermaid\nsequenceDiagram\n User->>QuivrRAG: ask(question)\n QuivrRAG->>VectorDB: search(query, n_results)\n VectorDB-->>QuivrRAG: relevant_chunks\n QuivrRAG->>LLMEndpoint: generate(prompt)\n LLMEndpoint->>LLM: chat.completions.create\n LLM-->>LLMEndpoint: response\n LLMEndpoint-->>QuivrRAG: ParsedRAGChunkResponse\n QuivrRAG-->>User: RAGResponse\n```\n\n### 流式响应处理\n\nLLM 集成支持流式输出，通过 `answer_astream` 方法实现：\n\n```python\nasync for chunk in brain.asearch_stream(question):\n print(chunk.answer, end=\"\", flush=True)\n```\n\n流式响应的关键流程：\n\n1. 逐块接收 LLM 返回的响应\n2. 实时解析并格式化输出\n3. 最后一块包含完整的元数据\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:100-200]()\n\n## 工作流节点配置\n\nLLM 集成可配置在工作流节点中，通过 YAML 文件定义：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"retrieval\"]\n```\n\n### RetrievalConfig 配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `max_tokens` | `int` | 单次响应最大 token 数 |\n| `temperature` | `float` | 生成温度 |\n| `n_results` | `int` | 检索返回的结果数量 |\n\n资料来源：[core/quivr_core/rag/entities/config.py]()\n\n## 提示词模板\n\nQuivr 的 LLM 集成使用结构化的提示词模板系统：\n\n### 模板类型\n\n| 模板名称 | 用途 |\n|----------|------|\n| `CONDENSE_QUESTION` | 问题改写模板 |\n| `DEFAULT_ANSWER` | 默认回答模板 |\n| `HISTORY_AUGMENT` | 历史增强模板 |\n\n### 自定义提示词\n\n可以通过 `custom_prompts` 配置自定义提示词：\n\n```python\nfrom quivr_core.rag.prompts import custom_prompts, TemplatePromptName\n\ncustom_prompts[TemplatePromptName.DEFAULT_ANSWER] = {\n \"prompt\": \"自定义提示词模板...\",\n \"guidelines\": \"自定义指南...\"\n}\n```\n\n资料来源：[core/quivr_core/rag/prompts.py]()\n\n## LangChain 集成\n\nQuivr 的 LLM 集成深度集成 LangChain 生态系统：\n\n### LangChain 兼容性\n\n```python\nfrom langchain_core.language_models import FakeListChatModel\nfrom langchain_core.embeddings import DeterministicFakeEmbedding\nfrom quivr_core import Brain\n\n# 使用 Fake LLM 进行测试\nbrain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[\"./docs.pdf\"],\n llm=LLMEndpoint(\n llm=FakeListChatModel(responses=[\"测试回答\"]),\n llm_config=LLMEndpointConfig(model=\"fake_model\", llm_base_url=\"local\")\n ),\n embedder=DeterministicFakeEmbedding(size=20)\n)\n```\n\n### Langfuse 追踪集成\n\nLLM 调用支持 Langfuse 追踪，便于性能监控和调试：\n\n```python\nfrom quivr_core.rag.utils import LangfuseService\n\nlangfuse_service = LangfuseService()\nlangfuse_handler = langfuse_service.get_handler()\n```\n\n资料来源：[core/quivr_core/rag/quivr_rag_langgraph.py]()\n\n## 高级配置\n\n### 模型参数覆盖\n\n在 `Brain.ask()` 调用时可以覆盖默认配置：\n\n```python\nanswer = brain.ask(\n question,\n retrieval_config=RetrievalConfig(\n max_tokens=1000,\n temperature=0.5\n )\n)\n```\n\n### 多模型路由\n\nQuivr 支持在工作流中配置多模型路由：\n\n```python\n# 为不同节点指定不同模型\nconfig = RetrievalConfig(\n model_configs={\n \"rewrite\": {\"model\": \"gpt-3.5-turbo\", \"temperature\": 0.3},\n \"answer\": {\"model\": \"gpt-4\", \"temperature\": 0.7}\n }\n)\n```\n\n## 错误处理\n\nLLM 集成内置了完整的错误处理机制：\n\n| 错误类型 | 处理方式 |\n|----------|----------|\n| `APIError` | 重试机制，最多 3 次 |\n| `RateLimitError` | 指数退避等待 |\n| `AuthenticationError` | 抛出明确的认证错误 |\n| `TimeoutError` | 10 秒超时限制 |\n\n## 最佳实践\n\n### 1. 生产环境配置\n\n```python\nconfig = LLMEndpointConfig(\n model=\"gpt-4-turbo\",\n temperature=0.3, # 降低随机性\n max_tokens=2000,\n streaming=True\n)\n```\n\n### 2. 成本优化\n\n- 使用 `gpt-3.5-turbo` 处理简单查询\n- 启用流式输出减少感知延迟\n- 合理设置 `max_tokens` 避免浪费\n\n### 3. 安全性\n\n- 使用环境变量存储 API 密钥\n- 避免在日志中记录敏感信息\n- 实施请求频率限制\n\n## 总结\n\nQuivr 的 LLM 集成模块提供了灵活、高效的大语言模型集成方案。通过统一的 `LLMEndpoint` 接口，开发者可以轻松切换不同的模型提供商，同时保持 RAG 工作流的稳定性。深度集成的 LangChain 支持和完善的配置管理使 Quivr 成为构建智能问答系统的理想选择。\n\n---\n\n\n\n## 工具扩展系统\n\n### 相关页面\n\n相关主题：[LLM 集成](#page-llm), [工作流配置](#page-workflow)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/README.md](https://github.com/QuivrHQ/quivr/blob/main/core/README.md)\n- [README.md](https://github.com/QuivrHQ/quivr/blob/main/README.md)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n
\n\n# 工具扩展系统\n\n## 概述\n\nQuivr 的工具扩展系统是实现 RAG（检索增强生成）工作流自定义的核心组件，允许用户为 LLM（大语言模型）集成额外的工具能力，如网络搜索、API 调用等。根据项目文档，Quivr 支持\"添加工具\"（add tools）功能，使用户能够扩展基础 RAG 的能力范围。\n\n资料来源：[README.md:1-50]()\n\n## 架构设计\n\n### 工具系统与 RAG 的关系\n\n工具扩展系统与 `QuivrQARAG` 类紧密集成。根据源码设计，`QuivrQARAG` 接受 `RetrievalConfig` 配置，并支持在检索过程中注入重排序（reranker）等扩展组件。这种模块化设计使得工具系统可以无缝嵌入 RAG 工作流。\n\n```mermaid\ngraph TD\n A[用户查询] --> B[QuivrQARAG]\n B --> C{检索配置}\n C --> D[向量存储检索]\n C --> E[历史过滤]\n C --> F[查询改写]\n D --> G[工具扩展层]\n G --> H[LLM 端点]\n H --> I[生成回答]\n \n F -->|可选| J[网络搜索工具]\n G -->|可扩展| K[自定义工具]\n```\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:50-80]()\n\n### 核心组件结构\n\n根据项目架构设计，工具扩展系统涉及以下核心组件：\n\n| 组件 | 作用 | 位置 |\n|------|------|------|\n| LLMEndpoint | LLM 调用端点封装 | core/quivr_core/llm/ |\n| RetrievalConfig | 检索配置管理 | core/quivr_core/rag/entities/config.py |\n| QuivrQARAG | RAG 核心引擎 | core/quivr_core/rag/quivr_rag.py |\n| Brain | 大脑抽象层 | core/quivr_core/brain/brain.py |\n\n资料来源：[core/quivr_core/brain/brain.py:1-100]()\n\n## 配置与使用\n\n### 基础配置流程\n\n用户可以通过 YAML 配置文件定义工具扩展的工作流程：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"END\"]\n```\n\n资料来源：[README.md:1-100]()\n\n### LLM 端点配置\n\n工具系统支持多种 LLM 提供商，包括：\n\n- **OpenAI**：通过 `OPENAI_API_KEY` 环境变量配置\n- **Anthropic**：支持 Claude 系列模型\n- **Mistral**：支持 Mistral AI 模型\n- **Ollama**：支持本地模型部署\n\n```python\nfrom quivr_core.config import RetrievalConfig\n\nconfig_file_name = \"./basic_rag_workflow.yaml\"\nretrieval_config = RetrievalConfig.from_yaml(config_file_name)\n```\n\n资料来源：[README.md:1-80]()\n\n## 工作流程集成\n\n### 问答流程\n\n工具扩展系统在 `Brain.ask()` 方法中被调用，完整流程如下：\n\n1. **历史过滤**（filter_history）：过滤相关聊天历史\n2. **查询改写**（rewrite）：优化用户查询\n3. **检索**（retrieve）：从向量数据库获取相关内容\n4. **工具执行**（可选）：如网络搜索等扩展工具\n5. **生成回答**：LLM 基于检索结果和工具输出生成答案\n\n```mermaid\ngraph LR\n A[用户提问] --> B[filter_history]\n B --> C[rewrite]\n C --> D{是否需要工具}\n D -->|是| E[执行工具]\n D -->|否| F[直接检索]\n E --> F\n F --> G[LLM 生成]\n G --> H[返回答案]\n```\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:100-150]()\n\n### 异步搜索接口\n\n`Brain` 类提供了异步搜索方法，支持灵活的工具扩展集成：\n\n```python\nasync def asearch(\n self,\n query: str | Document,\n n_results: int = 5,\n filter: Callable | Dict[str, Any] | None = None,\n fetch_n_neighbors: int = 20,\n) -> list[SearchResult]\n```\n\n资料来源：[core/quivr_core/brain/brain.py:100-120]()\n\n## 扩展机制\n\n### 自定义工具注册\n\n根据项目架构设计，工具系统支持用户注册自定义处理器和加载器：\n\n```python\nfrom quivr_core.processor.processor_base import ProcessorBase\nfrom quivr_core.files.file import FileExtension, QuivrFile\n\nclass CustomProcessor(ProcessorBase):\n supported_extensions = [\".custom\"]\n \n async def process_file_inner(self, file: QuivrFile) -> ProcessedDocument:\n # 自定义处理逻辑\n pass\n```\n\n资料来源：[core/quivr_core/processor/implementations/default.py:1-50]()\n\n### 支持的文件格式\n\n工具系统通过处理器基类支持多种文件格式：\n\n| 格式 | 处理器 | 状态 |\n|------|--------|------|\n| PDF | UnstructuredPDFLoader | 支持 |\n| TXT | TextLoader | 支持 |\n| Markdown | UnstructuredMarkdownLoader | 支持 |\n| DOCX | Docx2txtLoader | 支持 |\n| CSV | CSVLoader | 支持 |\n| Excel | UnstructuredExcelLoader | 支持 |\n| HTML | UnstructuredHTMLLoader | 支持 |\n\n资料来源：[core/quivr_core/processor/implementations/default.py:10-30]()\n\n## 版本与兼容性\n\n工具扩展系统随 `quivr-core` 包发布，版本信息记录在文档元数据中：\n\n```python\nqvr_version = version(\"quivr-core\")\ndoc.metadata = {\n \"chunk_index\": idx,\n \"quivr_core_version\": qvr_version,\n \"language\": detect_language(text=...).value,\n **file.metadata,\n **doc.metadata,\n **self.processor_metadata,\n}\n```\n\n资料来源：[core/quivr_core/processor/processor_base.py:20-40]()\n\n## 快速开始\n\n### 完整示例\n\n```python\nimport tempfile\nfrom quivr_core import Brain\nfrom quivr_core.config import RetrievalConfig\n\n# 创建 Brain\nbrain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[\"./documents/\"],\n)\n\n# 配置检索（含工具扩展）\nretrieval_config = RetrievalConfig.from_yaml(\"./config.yaml\")\n\n# 提问\nanswer = brain.ask(\n \"您的技术问题\",\n retrieval_config=retrieval_config\n)\n\nprint(answer.answer)\n```\n\n资料来源：[README.md:40-70]()\n\n## 总结\n\nQuivr 的工具扩展系统通过模块化设计，将 LLM 工具能力与 RAG 工作流深度整合。系统支持自定义工具注册、多 LLM 提供商集成，以及灵活的工作流配置，为构建智能问答应用提供了强大的扩展基础。开发者可以通过继承 `ProcessorBase` 类或配置 YAML 工作流文件来扩展系统能力。\n\n---\n\n\n\n## 工作流配置\n\n### 相关页面\n\n相关主题：[RAG 处理流程](#page-rag-flow)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [examples/chatbot/basic_rag_workflow.yaml](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot/basic_rag_workflow.yaml)\n- [examples/chatbot_voice/basic_rag_workflow.yaml](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot_voice/basic_rag_workflow.yaml)\n- [core/example_workflows/talk_to_file_rag_config_workflow.yaml](https://github.com/QuivrHQ/quivr/blob/main/core/example_workflows/talk_to_file_rag_config_workflow.yaml)\n- [core/quivr_core/rag/entities/config.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/config.py)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/rag/quivr_rag_langgraph.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag_langgraph.py)\n- [core/quivr_core/rag/prompts.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/prompts.py)\n
\n\n# 工作流配置\n\n## 概述\n\n工作流配置（Workflow Configuration）是 Quivr Core 框架中用于定义 RAG（检索增强生成）流程的核心机制。通过 YAML 格式的配置文件，用户可以灵活地定义检索、生成和对话历史处理的各个环节，实现高度定制化的问答系统。\n\n工作流配置的主要作用包括：\n\n- **定义处理流程节点**：指定 RAG 流程中的各个处理阶段（如历史过滤、问题改写、文档检索、答案生成）\n- **配置节点间连接**：通过边（edges）定义节点之间的执行顺序和数据流向\n- **控制对话历史**：设置历史消息的过滤策略和最大上下文长度\n- **配置重排序器**：选择重排序模型以提升检索结果质量\n- **调整 LLM 参数**：控制生成答案的最大输入令牌数和温度参数\n\n## 配置结构\n\n工作流配置文件采用 YAML 格式，整体结构如下：\n\n```yaml\nworkflow_config:\n name: \"工作流名称\"\n nodes:\n - name: \"节点名称\"\n edges: [\"下一节点名称\"]\n\nmax_history: 10\n\nreranker_config:\n supplier: \"cohere\"\n model: \"rerank-multilingual-v3.0\"\n top_n: 5\n\nllm_config:\n max_input_tokens: 4000\n temperature: 0.7\n```\n\n## 核心配置项\n\n### workflow_config（工作流配置）\n\n定义 RAG 处理流程的节点拓扑结构。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 工作流名称，用于标识和日志记录 |\n| nodes | list | 是 | 节点列表，每个节点定义一个处理阶段 |\n\n**节点定义**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 节点唯一标识名称 |\n| edges | list | 是 | 该节点的出边列表，指定下一个执行的节点 |\n\n节点名称必须是预定义的系统节点，当前支持的节点包括：\n\n- `START`：流程起始节点\n- `filter_history`：对话历史过滤节点\n- `rewrite`：问题改写节点\n- `retrieve`：文档检索节点\n- `generate_rag`：RAG 答案生成节点（通常是最后一个节点）\n- `END`：流程结束节点\n\n资料来源：[examples/chatbot/basic_rag_workflow.yaml:1-22]()\n\n### max_history（历史消息配置）\n\n控制对话历史中包含的最大迭代次数。\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| max_history | int | 10 | 包含在答案上下文中的历史对话轮次数量 |\n\n此参数用于限制传入 LLM 的历史消息数量，防止上下文过长导致令牌浪费和性能下降。\n\n### reranker_config（重排序配置）\n\n配置文档重排序器以提升检索结果的相关性。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| supplier | string | 是 | 重排序服务提供商（如 `cohere`） |\n| model | string | 是 | 具体使用的重排序模型名称 |\n| top_n | int | 是 | 重排序后返回的文档块数量 |\n\n当前支持的重排序供应商包括 `cohere`，模型推荐使用 `rerank-multilingual-v3.0`。\n\n资料来源：[examples/chatbot/basic_rag_workflow.yaml:24-32]()\n\n### llm_config（语言模型配置）\n\n配置用于答案生成的大语言模型参数。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| max_input_tokens | int | 是 | 传递给 LLM 的最大输入令牌数 |\n| temperature | float | 是 | LLM 生成答案的温度参数（0-1之间） |\n\n- `temperature` 越低，答案越确定性；越高，答案越有创造性\n- `max_input_tokens` 应根据 LLM 的上下文窗口和文档数量合理设置\n\n## 工作流执行流程\n\n### 标准 RAG 流程图\n\n```mermaid\ngraph TD\n START([START]) --> FILTER[filter_history]\n FILTER --> REWRITE[rewrite]\n REWRITE --> RETRIEVE[retrieve]\n RETRIEVE --> GENERATE[generate_rag]\n GENERATE --> END([END])\n \n style START fill:#90EE90\n style END fill:#FFB6C1\n```\n\n### 各节点功能详解\n\n#### filter_history（历史过滤）\n\n该节点负责过滤和精简对话历史，只保留最近 N 轮对话内容。配置参数为 `max_history`，用于控制保留的历史对话对数。\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:120-140]()\n\n#### rewrite（问题改写）\n\n将用户当前问题与对话历史结合，改写为独立的、上下文无关的问题，以便更好地进行文档检索。这一步确保即使问题依赖历史上下文，也能准确检索相关文档。\n\n#### retrieve（文档检索）\n\n基于改写后的问题，从向量数据库中检索最相关的文档块。检索结果的数量由 `reranker_config.top_n` 控制。\n\n#### generate_rag（答案生成）\n\n将检索到的文档块与问题、历史上下文结合，调用 LLM 生成最终答案。最终节点的输出会流式返回给用户。\n\n## 配置类定义\n\n工作流配置在代码中由以下数据类定义：\n\n```python\nclass RetrievalConfig(BaseModel):\n max_history: int = 10\n prompt: Optional[str] = None\n reranker_config: Optional[RerankerConfig] = None\n llm_config: Optional[LLMConfig] = None\n```\n\n资料来源：[core/quivr_core/rag/entities/config.py]()\n\n### RerankerConfig（重排序配置类）\n\n```python\nclass RerankerConfig(BaseModel):\n supplier: str\n model: str\n top_n: int\n```\n\n### LLMConfig（语言模型配置类）\n\n```python\nclass LLMConfig(BaseModel):\n max_input_tokens: int\n temperature: float\n```\n\n### NodeConfig（节点配置类）\n\n```python\nclass NodeConfig(BaseModel):\n name: str\n edges: List[str]\n```\n\n## 使用示例\n\n### 基本 RAG 工作流配置\n\n创建文件 `basic_rag_workflow.yaml`：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n\n - name: \"rewrite\"\n edges: [\"retrieve\"]\n\n - name: \"retrieve\"\n edges: [\"generate_rag\"]\n\n - name: \"generate_rag\"\n edges: [\"END\"]\n\nmax_history: 10\n\nreranker_config:\n supplier: \"cohere\"\n model: \"rerank-multilingual-v3.0\"\n top_n: 5\n\nllm_config:\n max_input_tokens: 4000\n temperature: 0.7\n```\n\n资料来源：[examples/chatbot/basic_rag_workflow.yaml:1-32]()\n\n### 在代码中使用配置\n\n```python\nfrom quivr_core import Brain\nfrom quivr_core.config import RetrievalConfig\n\nconfig_file_name = \"./basic_rag_workflow.yaml\"\nretrieval_config = RetrievalConfig.from_yaml(config_file_name)\n\nbrain = Brain.from_files(\n name=\"my_smart_brain\",\n file_paths=[\"./my_first_doc.pdf\", \"./my_second_doc.txt\"],\n)\n\nanswer = brain.ask(\n \"what is gold?\",\n retrieval_config=retrieval_config\n)\n```\n\n### 语音聊天工作流配置\n\n语音聊天场景的工作流配置与基本 RAG 类似，主要区别在于支持音频输入和语音合成：\n\n```yaml\nworkflow_config:\n name: \"voice RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n\n - name: \"rewrite\"\n edges: [\"retrieve\"]\n\n - name: \"retrieve\"\n edges: [\"generate_rag\"]\n\n - name: \"generate_rag\"\n edges: [\"END\"]\n\nmax_history: 10\n\nreranker_config:\n supplier: \"cohere\"\n model: \"rerank-multilingual-v3.0\"\n top_n: 5\n\nllm_config:\n max_input_tokens: 4000\n temperature: 0.7\n```\n\n资料来源：[examples/chatbot_voice/basic_rag_workflow.yaml:1-32]()\n\n## 高级配置：自定义提示词\n\n除了系统默认的提示词模板外，用户可以通过 `llm_config.prompt` 参数添加自定义指令：\n\n```yaml\nllm_config:\n max_input_tokens: 4000\n temperature: 0.7\n prompt: |\n 请用简洁的语言回答，并在答案开头用一句话总结。\n```\n\n自定义提示词会与系统默认指令合并，系统会在生成答案时综合考虑两者的要求。\n\n## LangGraph 高级工作流\n\nQuivr 还支持基于 LangGraph 的高级工作流，通过 `quivr_rag_langgraph.py` 模块实现：\n\n```python\nfrom quivr_core.rag.quivr_rag_langgraph import QuivrRAGLangGraph\n\nrag = QuivrRAGLangGraph(\n retrieval_config=retrieval_config,\n brain=brain,\n)\n```\n\nLangGraph 工作流支持更复杂的条件分支和状态管理，适合需要多步骤推理的应用场景。\n\n资料来源：[core/quivr_core/rag/quivr_rag_langgraph.py]()\n\n## 最佳实践\n\n### 1. 合理设置 max_history\n\n- **低值（1-3）**：适用于简单问答场景，减少上下文长度\n- **中值（5-10）**：适用于需要多轮对话的应用\n- **高值（15+）**：适用于长对话分析，但会增加令牌消耗\n\n### 2. 优化 top_n 参数\n\n- **文档简短**：可设置较高值（10-20）\n- **文档冗长**：建议设置较低值（3-5），减少上下文干扰\n\n### 3. 调整 temperature\n\n- **事实性问答**：建议 0.1-0.3\n- **创意性生成**：建议 0.7-0.9\n- **平衡场景**：建议 0.5 左右\n\n### 4. 配置加载方式\n\n支持从 YAML 文件或 Python 代码直接配置：\n\n```python\n# 从 YAML 加载\nconfig = RetrievalConfig.from_yaml(\"config.yaml\")\n\n# 直接创建\nconfig = RetrievalConfig(\n max_history=5,\n reranker_config=RerankerConfig(\n supplier=\"cohere\",\n model=\"rerank-multilingual-v3.0\",\n top_n=5\n ),\n llm_config=LLMConfig(\n max_input_tokens=4000,\n temperature=0.7\n )\n)\n```\n\n## 相关文件\n\n| 文件路径 | 说明 |\n|----------|------|\n| `core/quivr_core/rag/entities/config.py` | 配置数据类定义 |\n| `core/quivr_core/rag/quivr_rag.py` | 标准 RAG 工作流实现 |\n| `core/quivr_core/rag/quivr_rag_langgraph.py` | LangGraph 工作流实现 |\n| `core/quivr_core/rag/prompts.py` | 提示词模板定义 |\n| `examples/chatbot/basic_rag_workflow.yaml` | 聊天机器人示例配置 |\n| `examples/chatbot_voice/basic_rag_workflow.yaml` | 语音聊天示例配置 |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：QuivrHQ/quivr\n\n摘要：发现 17 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：EU AI Act Compliance Scan Results — Sharing Findings for Feedback。\n\n## 1. 安全/权限坑 · 来源证据：EU AI Act Compliance Scan Results — Sharing Findings for Feedback\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：EU AI Act Compliance Scan Results — Sharing Findings for Feedback\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_46118108af95480ba852109be6e2c66a | https://github.com/QuivrHQ/quivr/issues/3667 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：[Bug]:\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]:\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff260ca3ab5247679b2ded201ec21e24 | https://github.com/QuivrHQ/quivr/issues/2004 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Integration idea: Screenpipe for screen/audio context\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Integration idea: Screenpipe for screen/audio context\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3a7f345691d04bbea72b03858746645e | https://github.com/QuivrHQ/quivr/issues/3658 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e3091b23b6184dffb982e0cc494134fd | https://github.com/QuivrHQ/quivr/issues/3650 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 能力判断依赖假设\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:640079149 | https://github.com/QuivrHQ/quivr | README/documentation is current enough for a first validation pass.\n\n## 6. 运行坑 · 来源证据：The garbage collector is trying to clean up non-checked-in connection >, which will…\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6fdde799a2b4f53806121190979025a | https://github.com/QuivrHQ/quivr/issues/3654 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 运行坑 · 来源证据：core: v0.0.25\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.25\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7c6096fb5a6442c7b53068a8dd8e2c78 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.25 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 运行坑 · 来源证据：core: v0.0.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.29\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7eeeeb626a10476e820fcd651727a55a | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.29 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 运行坑 · 来源证据：core: v0.0.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.33\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7a735cb41bc44f2abeb148d689f1320 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.33 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 来源证据：core: v0.0.24\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：core: v0.0.24\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5272fe70cda24220a5aeb994ad06819e | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.24 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · 来源证据：core: v0.0.26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：core: v0.0.26\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7f723b616fd446c3be43298d75fd6e8b | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.26 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:640079149 | https://github.com/QuivrHQ/quivr | last_activity_observed missing\n\n## 13. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:640079149 | https://github.com/QuivrHQ/quivr | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:640079149 | https://github.com/QuivrHQ/quivr | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：core: v0.0.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：core: v0.0.27\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_027338ba02764da6b371970615591265 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.27 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 维护坑 · 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:640079149 | https://github.com/QuivrHQ/quivr | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:640079149 | https://github.com/QuivrHQ/quivr | release_recency=unknown\n\n\n", "markdown_key": "quivr", "pages": "draft", "source_refs": [ { "evidence_id": "github_repo:640079149", "kind": "repo", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/QuivrHQ/quivr" }, { "evidence_id": "art_508b34cf9ee340be9ef8db74ca412fc0", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/QuivrHQ/quivr#readme" } ], "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。", "title": "quivr 说明书", "toc": [ "https://github.com/QuivrHQ/quivr 项目说明书", "目录", "项目概述", "项目简介", "技术架构", "快速入门", "Brain 核心类", "RAG 工作流配置", "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": "947a785415c6c35ab2ae8157222b4720b0710b4d", "repo_inspection_error": null, "repo_inspection_files": [ "README.md", "docs/pyproject.toml", "docs/mkdocs.yml", "docs/README.md", "docs/docs/index.md", "docs/docs/quickstart.md", "docs/src/docs/__init__.py", "docs/docs/vectorstores/index.md", "docs/docs/vectorstores/pgvector.md", "docs/docs/vectorstores/faiss.md", "docs/docs/brain/index.md", "docs/docs/brain/brain.md", "docs/docs/brain/chat.md", "docs/docs/parsers/index.md", "docs/docs/parsers/megaparse.md", "docs/docs/parsers/simple.md", "docs/docs/config/index.md", "docs/docs/config/base_config.md", "docs/docs/config/config.md", "docs/docs/storage/index.md", "docs/docs/storage/local_storage.md", "docs/docs/storage/base.md", "docs/docs/examples/index.md", "docs/docs/examples/custom_storage.md", "docs/docs/examples/chatbot.md", "docs/docs/examples/chatbot_voice_flask.md", "docs/docs/examples/chatbot_voice.md", "docs/docs/workflows/index.md", "docs/docs/workflows/examples/basic_ingestion.md", "docs/docs/workflows/examples/basic_rag.md", "docs/docs/workflows/examples/rag_with_web_search.md", "examples/pdf_parsing_tika.py", "examples/save_load_brain.py", "examples/pdf_document_from_yaml.py", "examples/simple_question_megaparse.py", "examples/quivr-whisper/pyproject.toml", "examples/quivr-whisper/README.md", "examples/quivr-whisper/app.py", "examples/chatbot/pyproject.toml", "examples/chatbot/main.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": "# quivr - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 quivr 编译的 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- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`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 quivr-core # Check that the installation worked` 证据：`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- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（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）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\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- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `core/tests/conftest.py`, `core/tests/test_llm_endpoint.py`, `docs/docs/examples/chatbot.md` 等\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- 文件总数：210\n- 重要文件覆盖：40/210\n- 证据索引条目：80\n- 角色 / Skill 条目：39\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请基于 quivr 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 quivr 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 quivr 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 39 个角色 / Skill / 项目文档条目。\n\n- **docs**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/README.md`\n- **Quivr - Your Second Brain, Empowered by Generative AI**（project_doc）：Quivr - Your Second Brain, Empowered by Generative AI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **quivr-core package**（project_doc）：This project is licensed under the Apache 2.0 License 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/README.md`\n- **Quivr Chatbot Example**（project_doc）：This example demonstrates how to create a simple chatbot using Quivr and Chainlit. The chatbot allows users to upload a text file and then ask questions about its content. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/chatbot/README.md`\n- **Quivr Chatbot Example**（project_doc）：This example demonstrates how to create a simple chatbot using Quivr and Chainlit. The chatbot allows users to upload a text file and then ask questions about its content. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/chatbot_voice/README.md`\n- **Quivr-Whisper**（project_doc）：Quivr-Whisper is a web application that allows users to ask questions via audio input. It leverages OpenAI's Whisper model for speech transcription and synthesizes responses using OpenAI's text-to-speech capabilities. The application queries the Quivr API to get a response based on the transcribed audio input. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/quivr-whisper/README.md`\n- **simple-question**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/simple_question/README.md`\n- **Brain**（project_doc）：::: quivr core.brain.brain options: heading level: 2 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/brain/brain.md`\n- **ChatHistory**（project_doc）：The ChatHistory class is where all the conversation between the user and the LLM gets stored. A ChatHistory object will transparently be instanciated in the Brain every time you create one. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/brain/chat.md`\n- **Brain**（project_doc）：The brain is the essential component of Quivr that stores and processes the knowledge you want to retrieve informations from. Simply create a brain with the files you want to process and use the latest Quivr RAG workflow to retrieve informations from the knowledge. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/brain/index.md`\n- **Configuration Base Class**（project_doc）：::: quivr core.base config options: heading level: 2 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/config/base_config.md`\n- **Configuration**（project_doc）：Retrieval Configuration ::: quivr core.rag.entities.config.RetrievalConfig 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/config/config.md`\n- **Configuration**（project_doc）：The configuration classes are based on Pydantic https://docs.pydantic.dev/latest/ and allow the configuration of the ingestion and retrieval workflows via YAML files. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/config/index.md`\n- **Chatbot with Chainlit**（project_doc）：This example demonstrates a simple chatbot using Quivr and Chainlit , where users can upload a .txt file and ask questions based on its content. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/examples/chatbot.md`\n- **Voice Chatbot with Chainlit**（project_doc）：This example demonstrates how to create a voice-enabled chatbot using Quivr and Chainlit . The chatbot lets users upload a text file, ask questions about its content, and interact using speech. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/examples/chatbot_voice.md`\n- **Voice Chatbot with Flask**（project_doc）：This example demonstrates a simple chatbot using Flask and Quivr , where users can upload a .txt file and ask questions based on its content. It supports speech-to-text and text-to-speech capabilities for a seamless interactive experience. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/examples/chatbot_voice_flask.md`\n- **Transparent Storage**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/examples/custom_storage.md`\n- **Examples**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/examples/index.md`\n- **Welcome to Quivr Documentation**（project_doc）：Quivr, helps you build your second brain, utilizes the power of GenerativeAI to be your personal assistant ! 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/index.md`\n- **Parsers**（project_doc）：Quivr provides a suite of parsers to extract structured data from various sources. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/parsers/index.md`\n- **Megaparse**（project_doc）：::: quivr core.processor.implementations.megaparse processor options: heading level: 2 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/parsers/megaparse.md`\n- **Simple Txt**（project_doc）：::: quivr core.processor.implementations.simple txt processor options: heading level: 2 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/parsers/simple.md`\n- **Quick start**（project_doc）：If you need to quickly start talking to your list of files, here are the steps. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/quickstart.md`\n- **StorageBase**（project_doc）：::: quivr core.storage.storage base options: heading level: 2 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/storage/base.md`\n- **🗄️ Storage**（project_doc）：Your Brain’s File Management System 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/storage/index.md`\n- **LocalStorage**（project_doc）：::: quivr core.storage.local storage options: heading level: 2 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/storage/local_storage.md`\n- **Faiss**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/vectorstores/faiss.md`\n- **Vector Stores**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/vectorstores/index.md`\n- **PGVector**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/vectorstores/pgvector.md`\n- **Basic ingestion**（project_doc）：Creating a basic ingestion workflow like the one above is simple, here are the steps: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/workflows/examples/basic_ingestion.md`\n- **Basic RAG**（project_doc）：Creating a basic RAG workflow like the one above is simple, here are the steps: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/workflows/examples/basic_rag.md`\n- **RAG with web search**（project_doc）：! rag with web search.excalidraw.png 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/workflows/examples/rag_with_web_search.md`\n- **Workflows**（project_doc）：In this section, you will find examples of workflows that you can use to create your own agentic RAG systems. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/docs/workflows/index.md`\n- **Description**（project_doc）：Please include a summary of the changes and the related issue. Please also include relevant motivation and context. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Changelog**（project_doc）：What's Changed feat: Add new documentation files by @StanGirard in https://github.com/QuivrHQ/quivr/pull/3351 fix: separate english and french ingredients by @chloedia in https://github.com/QuivrHQ/quivr/pull/3358 docs core : init by @StanGirard in https://github.com/QuivrHQ/quivr/pull/3365 docs: quivr core storage by @AmineDiro in https://github.com/QuivrHQ/quivr/pull/3366 fix: fixing pdf parsing by @jacopo-chevall… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Changelog**（project_doc）：0.0.33 https://github.com/QuivrHQ/quivr/compare/core-0.0.32...core-0.0.33 2025-02-03 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/CHANGELOG.md`\n- **Quivr Chatbot Example**（project_doc）：This example demonstrates how to create a simple chatbot using Quivr and Chainlit. The chatbot allows users to upload a text file and then ask questions about its content. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/chatbot/chainlit.md`\n- **Quivr Chatbot Example**（project_doc）：This example demonstrates how to create a simple chatbot using Quivr and Chainlit. The chatbot allows users to upload a text file and then ask questions about its content. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/chatbot_voice/chainlit.md`\n- **Backend code guidelines**（project_doc）：- Follow a clear project structure : - In quivr-api we have modules divided into : controller, entity, services, repositories, utils - Use dependency injection for better testability and modularity 🔺 - Use environment variables for configuration 🔺 - We use Pydantic settings for parsing the arguments - Don’t add unnecessary abstractions → KISS principle. - Premature abstractions are a bad pattern - Avoid using Global… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`core/tests/processor/data/guidelines_code.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **docs**（documentation）：docs Describe your project here. 证据：`docs/README.md`\n- **Quivr - Your Second Brain, Empowered by Generative AI**（documentation）：Quivr - Your Second Brain, Empowered by Generative AI 证据：`README.md`\n- **quivr-core package**（documentation）：This project is licensed under the Apache 2.0 License 证据：`core/README.md`\n- **Quivr Chatbot Example**（documentation）：This example demonstrates how to create a simple chatbot using Quivr and Chainlit. The chatbot allows users to upload a text file and then ask questions about its content. 证据：`examples/chatbot/README.md`\n- **Quivr Chatbot Example**（documentation）：This example demonstrates how to create a simple chatbot using Quivr and Chainlit. The chatbot allows users to upload a text file and then ask questions about its content. 证据：`examples/chatbot_voice/README.md`\n- **Quivr-Whisper**（documentation）：Quivr-Whisper is a web application that allows users to ask questions via audio input. It leverages OpenAI's Whisper model for speech transcription and synthesizes responses using OpenAI's text-to-speech capabilities. The application queries the Quivr API to get a response based on the transcribed audio input. 证据：`examples/quivr-whisper/README.md`\n- **simple-question**（documentation）：simple-question Describe your project here. 证据：`examples/simple_question/README.md`\n- **License**（source_file）：Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ 证据：`LICENSE`\n- **Brain**（documentation）：::: quivr core.brain.brain options: heading level: 2 证据：`docs/docs/brain/brain.md`\n- **ChatHistory**（documentation）：The ChatHistory class is where all the conversation between the user and the LLM gets stored. A ChatHistory object will transparently be instanciated in the Brain every time you create one. 证据：`docs/docs/brain/chat.md`\n- **Brain**（documentation）：The brain is the essential component of Quivr that stores and processes the knowledge you want to retrieve informations from. Simply create a brain with the files you want to process and use the latest Quivr RAG workflow to retrieve informations from the knowledge. 证据：`docs/docs/brain/index.md`\n- **Configuration Base Class**（documentation）：::: quivr core.base config options: heading level: 2 证据：`docs/docs/config/base_config.md`\n- **Configuration**（documentation）：Retrieval Configuration ::: quivr core.rag.entities.config.RetrievalConfig 证据：`docs/docs/config/config.md`\n- **Configuration**（documentation）：The configuration classes are based on Pydantic https://docs.pydantic.dev/latest/ and allow the configuration of the ingestion and retrieval workflows via YAML files. 证据：`docs/docs/config/index.md`\n- **Chatbot with Chainlit**（documentation）：This example demonstrates a simple chatbot using Quivr and Chainlit , where users can upload a .txt file and ask questions based on its content. 证据：`docs/docs/examples/chatbot.md`\n- **Voice Chatbot with Chainlit**（documentation）：This example demonstrates how to create a voice-enabled chatbot using Quivr and Chainlit . The chatbot lets users upload a text file, ask questions about its content, and interact using speech. 证据：`docs/docs/examples/chatbot_voice.md`\n- **Voice Chatbot with Flask**（documentation）：This example demonstrates a simple chatbot using Flask and Quivr , where users can upload a .txt file and ask questions based on its content. It supports speech-to-text and text-to-speech capabilities for a seamless interactive experience. 证据：`docs/docs/examples/chatbot_voice_flask.md`\n- **Transparent Storage**（documentation）：Transparent Storage todo 证据：`docs/docs/examples/custom_storage.md`\n- **Examples**（documentation）：Examples 证据：`docs/docs/examples/index.md`\n- **Welcome to Quivr Documentation**（documentation）：Quivr, helps you build your second brain, utilizes the power of GenerativeAI to be your personal assistant ! 证据：`docs/docs/index.md`\n- **Parsers**（documentation）：Quivr provides a suite of parsers to extract structured data from various sources. 证据：`docs/docs/parsers/index.md`\n- **Megaparse**（documentation）：::: quivr core.processor.implementations.megaparse processor options: heading level: 2 证据：`docs/docs/parsers/megaparse.md`\n- **Simple Txt**（documentation）：::: quivr core.processor.implementations.simple txt processor options: heading level: 2 证据：`docs/docs/parsers/simple.md`\n- **Quick start**（documentation）：If you need to quickly start talking to your list of files, here are the steps. 证据：`docs/docs/quickstart.md`\n- **StorageBase**（documentation）：::: quivr core.storage.storage base options: heading level: 2 证据：`docs/docs/storage/base.md`\n- **🗄️ Storage**（documentation）：Your Brain’s File Management System 证据：`docs/docs/storage/index.md`\n- **LocalStorage**（documentation）：::: quivr core.storage.local storage options: heading level: 2 证据：`docs/docs/storage/local_storage.md`\n- **Faiss**（documentation）：Faiss 证据：`docs/docs/vectorstores/faiss.md`\n- **Vector Stores**（documentation）：Vector Stores 证据：`docs/docs/vectorstores/index.md`\n- **PGVector**（documentation）：PGVector 证据：`docs/docs/vectorstores/pgvector.md`\n- **Basic ingestion**（documentation）：Creating a basic ingestion workflow like the one above is simple, here are the steps: 证据：`docs/docs/workflows/examples/basic_ingestion.md`\n- **Basic RAG**（documentation）：Creating a basic RAG workflow like the one above is simple, here are the steps: 证据：`docs/docs/workflows/examples/basic_rag.md`\n- **RAG with web search**（documentation）：! rag with web search.excalidraw.png 证据：`docs/docs/workflows/examples/rag_with_web_search.md`\n- **Workflows**（documentation）：In this section, you will find examples of workflows that you can use to create your own agentic RAG systems. 证据：`docs/docs/workflows/index.md`\n- **Description**（documentation）：Please include a summary of the changes and the related issue. Please also include relevant motivation and context. 证据：`.github/PULL_REQUEST_TEMPLATE.md`\n- **Changelog**（documentation）：What's Changed feat: Add new documentation files by @StanGirard in https://github.com/QuivrHQ/quivr/pull/3351 fix: separate english and french ingredients by @chloedia in https://github.com/QuivrHQ/quivr/pull/3358 docs core : init by @StanGirard in https://github.com/QuivrHQ/quivr/pull/3365 docs: quivr core storage by @AmineDiro in https://github.com/QuivrHQ/quivr/pull/3366 fix: fixing pdf parsing by @jacopo-chevallard in https://github.com/QuivrHQ/quivr/pull/3349 feat: Improve user credit calculation in get user credits by @StanGirard in https://github.com/QuivrHQ/quivr/pull/3367 fix unwanted parsing effect by @chloedia in https://github.com/QuivrHQ/quivr/pull/3371 add fallback on llamapar… 证据：`CHANGELOG.md`\n- **Changelog**（documentation）：0.0.33 https://github.com/QuivrHQ/quivr/compare/core-0.0.32...core-0.0.33 2025-02-03 证据：`core/CHANGELOG.md`\n- **Quivr Chatbot Example**（documentation）：This example demonstrates how to create a simple chatbot using Quivr and Chainlit. The chatbot allows users to upload a text file and then ask questions about its content. 证据：`examples/chatbot/chainlit.md`\n- **Quivr Chatbot Example**（documentation）：This example demonstrates how to create a simple chatbot using Quivr and Chainlit. The chatbot allows users to upload a text file and then ask questions about its content. 证据：`examples/chatbot_voice/chainlit.md`\n- **.Release Please Manifest**（structured_config）：{ \"core\": \"0.0.33\" } 证据：`.release-please-manifest.json`\n- **Release Please Config**（structured_config）：{ \"packages\": { \"core\": { \"release-type\": \"python\", \"package-name\": \"core\", \"bump-patch-for-minor-pre-major\": true, \"include-v-in-tag\": false, \"tag-separator\": \"-\", \"component\": \"core\" } } } 证据：`release-please-config.json`\n- **Vercel**（structured_config）：{ \"git\": { \"deploymentEnabled\": { \"main\": false } } } 证据：`vercel.json`\n- **Bn**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u09b8\\u09c7\\u099f\\u09bf\\u0982\\u09b8\", \"settingsKey\": \"S\", \"APIKeys\": \"\\u098f\\u09aa\\u09bf\\u0986\\u0987 \\u0995\\u09c0\", \"logout\": \"\\u09b2\\u0997\\u0986\\u0989\\u099f\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u09a8\\u09a4\\u09c1\\u09a8 \\u0986\\u09a1\\u09cd\\u09a1\\u09be\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0995\\u09be\\u09b0\\u09cd\\u09af \\u09a4\\u09be\\u09b2\\u09bf\\u0995\\u09be\", \"loading\": \"\\u09b2\\u09cb\\u09a1\\u0964\\u0964\\u0964\", \"error\": \"\\u098f\\u0995\\u099f\\u09bf \\u09a4\\u09cd\\u09b0\\u09c1\\u099f\\u09bf \\u09b8\\u0982\\u0998\\u099f\\u09bf\\u09a4 \\u09b9\\u09af\\u09bc\\u09c7\\u099b\\u09c7\" } }, \"attachments\"… 证据：`examples/chatbot/.chainlit/translations/bn.json`\n- **En Us**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"Settings\", \"settingsKey\": \"S\", \"APIKeys\": \"API Keys\", \"logout\": \"Logout\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"New Chat\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f Task List\", \"loading\": \"Loading...\", \"error\": \"An error occurred\" } }, \"attachments\": { \"cancelUpload\": \"Cancel upload\", \"removeAttachment\": \"Remove attachment\" }, \"newChatDialog\": { \"createNewChat\": \"Create new chat?\", \"clearChat\": \"This will clear the current messages and start a new chat.\", \"cancel\": \"Cancel\", \"confirm\": \"Confirm\" }, \"settingsModal\": { \"settings\": \"Settings\", \"expandMessages\": \"Expand Messages\", \"… 证据：`examples/chatbot/.chainlit/translations/en-US.json`\n- **Gu**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0ab8\\u0ac1\\u0aaf\\u0acb\\u0a9c\\u0aa8\\u0acb\", \"settingsKey\": \"S\", \"APIKeys\": \"API \\u0a95\\u0ac0\\u0a93\", \"logout\": \"\\u0aac\\u0ab9\\u0abe\\u0ab0 \\u0aa8\\u0ac0\\u0a95\\u0ab3\\u0acb\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0aa8\\u0ab5\\u0acb \\u0ab8\\u0a82\\u0ab5\\u0abe\\u0aa6\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0a95\\u0abe\\u0ab0\\u0acd\\u0aaf \\u0aaf\\u0abe\\u0aa6\\u0ac0\", \"loading\": \"\\u0ab2\\u0acb\\u0aa1 \\u0a95\\u0ab0\\u0ac0 \\u0ab0\\u0ab9\\u0acd\\u0aaf\\u0abe \\u0a9b\\u0ac7...\", \"error\": \"\\u0aad\\u0ac2\\u0ab2 \\u0a89\\u0aa6\\u0acd\\u0aad\\u0ab5\\u0ac0\" } }, \"attachments\": { \"cancelUpload\": \"\\u0a85\\u0aaa\\u0ab2\\… 证据：`examples/chatbot/.chainlit/translations/gu.json`\n- **He Il**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u05d4\\u05d2\\u05d3\\u05e8\\u05d5\\u05ea\", \"settingsKey\": \"S\", \"APIKeys\": \"API Keys\", \"logout\": \"\\u05d4\\u05ea\\u05e0\\u05ea\\u05e7\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u05e6'\\u05d0\\u05d8 \\u05d7\\u05d3\\u05e9\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f Task List\", \"loading\": \"\\u05d8\\u05d5\\u05e2\\u05df...\", \"error\": \"\\u05e9\\u05d2\\u05d9\\u05d0\\u05d4\" } }, \"attachments\": { \"cancelUpload\": \"\\u05d1\\u05d8\\u05dc \\u05d4\\u05e2\\u05dc\\u05d0\\u05d4\", \"removeAttachment\": \"\\u05d4\\u05e1\\u05e8 \\u05e7\\u05d5\\u05d1\\u05e5 \\u05de\\u05e6\\u05d5\\u05e8\\u05e3\" }, \"newChatDialog\": { \"createNewChat\": \"\\u05e6\\u05d5\\u… 证据：`examples/chatbot/.chainlit/translations/he-IL.json`\n- **Hi**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0938\\u0947\\u091f\\u093f\\u0902\\u0917\\u094d\\u0938\", \"settingsKey\": \"\\u0926\\u0915\\u094d\\u0937\\u093f\\u0923\\u0940\", \"APIKeys\": \"\\u090f\\u092a\\u0940\\u0906\\u0908 \\u0915\\u0941\\u0902\\u091c\\u0940\", \"logout\": \"\\u0932\\u0949\\u0917\\u0906\\u0909\\u091f\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0928\\u0908 \\u091a\\u0948\\u091f\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0915\\u093e\\u0930\\u094d\\u092f \\u0938\\u0942\\u091a\\u0940\", \"loading\": \"\\u0932\\u094b\\u0921\\u0964\\u0964\\u0964\", \"error\": \"\\u0915\\u094b\\u0908 \\u0924\\u094d\\u0930\\u0941\\u091f\\u093f \\u0909\\u0924\\u094d\\u092a\\u0928\\u094d\\u0928 \\u0939\\u0941\\u0… 证据：`examples/chatbot/.chainlit/translations/hi.json`\n- **Kn**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0cb8\\u0cc6\\u0c9f\\u0ccd\\u0c9f\\u0cbf\\u0c82\\u0c97\\u0ccd \\u0c97\\u0cb3\\u0cc1\", \"settingsKey\": \"S\", \"APIKeys\": \"API \\u0c95\\u0cc0\\u0cb2\\u0cbf\\u0c97\\u0cb3\\u0cc1\", \"logout\": \"\\u0cb2\\u0cbe\\u0c97\\u0ccd \\u0c94\\u0c9f\\u0ccd\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0cb9\\u0cca\\u0cb8 \\u0c9a\\u0cbe\\u0c9f\\u0ccd\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0c95\\u0cbe\\u0cb0\\u0ccd\\u0caf \\u0caa\\u0c9f\\u0ccd\\u0c9f\\u0cbf\", \"loading\": \"\\u0cb2\\u0ccb\\u0ca1\\u0ccd \\u0c86\\u0c97\\u0cc1\\u0ca4\\u0ccd\\u0ca4\\u0cbf\\u0ca6\\u0cc6...\", \"error\": \"\\u0ca6\\u0ccb\\u0cb7 \\u0cb8\\u0c82\\u0cad\\u0cb5\\u0cbf\\u0cb8\\u0cbf\\u0ca6\\u0cc6\"… 证据：`examples/chatbot/.chainlit/translations/kn.json`\n- **Ml**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0d15\\u0d4d\\u0d30\\u0d2e\\u0d40\\u0d15\\u0d30\\u0d23\\u0d19\\u0d4d\\u0d19\\u0d7e\", \"settingsKey\": \"S\", \"APIKeys\": \"API \\u0d15\\u0d40\\u0d15\\u0d7e\", \"logout\": \"\\u0d32\\u0d4b\\u0d17\\u0d4b\\u0d1f\\u0d4d\\u0d1f\\u0d4d\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0d2a\\u0d41\\u0d24\\u0d3f\\u0d2f \\u0d1a\\u0d3e\\u0d31\\u0d4d\\u0d31\\u0d4d\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0d1f\\u0d3e\\u0d38\\u0d4d\\u0d15\\u0d4d \\u0d32\\u0d3f\\u0d38\\u0d4d\\u0d31\\u0d4d\\u0d31\\u0d4d\", \"loading\": \"\\u0d32\\u0d4b\\u0d21\\u0d3f\\u0d02\\u0d17\\u0d4d...\", \"error\": \"\\u0d12\\u0d30\\u0d41 \\u0d2a\\u0d3f\\u0d36\\u0d15\\u0d4d \\u0d38\\u0d02\\u0d2d\\u0d35\\u0… 证据：`examples/chatbot/.chainlit/translations/ml.json`\n- **Mr**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0938\\u0947\\u091f\\u093f\\u0902\\u0917\\u094d\\u0938\", \"settingsKey\": \"S\", \"APIKeys\": \"\\u090f\\u092a\\u0940\\u0906\\u092f \\u0915\\u0940\\u091c\", \"logout\": \"Logout\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0928\\u0935\\u0940\\u0928 \\u0917\\u092a\\u094d\\u092a\\u093e\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0915\\u093e\\u0930\\u094d\\u092f \\u0938\\u0942\\u091a\\u0940\", \"loading\": \"\\u0932\\u094b\\u0921\\u093f\\u0902\\u0917...\", \"error\": \"\\u090f\\u0915 \\u0924\\u094d\\u0930\\u0941\\u091f\\u0940 \\u091d\\u093e\\u0932\\u0940\" } }, \"attachments\": { \"cancelUpload\": \"\\u0905\\u092a\\u0932\\u094b\\u0921 \\u0930\\u0926\\u094d\\u0926… 证据：`examples/chatbot/.chainlit/translations/mr.json`\n- **Ta**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0b85\\u0bae\\u0bc8\\u0baa\\u0bcd\\u0baa\\u0bc1\\u0b95\\u0bb3\\u0bcd\", \"settingsKey\": \"S\", \"APIKeys\": \"API \\u0bb5\\u0bbf\\u0b9a\\u0bc8\\u0b95\\u0bb3\\u0bcd\", \"logout\": \"\\u0bb5\\u0bc6\\u0bb3\\u0bbf\\u0baf\\u0bc7\\u0bb1\\u0bc1\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0baa\\u0bc1\\u0ba4\\u0bbf\\u0baf \\u0b85\\u0bb0\\u0b9f\\u0bcd\\u0b9f\\u0bc8\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0baa\\u0ba3\\u0bbf \\u0baa\\u0b9f\\u0bcd\\u0b9f\\u0bbf\\u0baf\\u0bb2\\u0bcd\", \"loading\": \"\\u0b8f\\u0bb1\\u0bcd\\u0bb1\\u0bc1\\u0b95\\u0bbf\\u0bb1\\u0ba4\\u0bc1...\", \"error\": \"\\u0b92\\u0bb0\\u0bc1 \\u0baa\\u0bbf\\u0bb4\\u0bc8 \\u0b8f\\u0bb1\\u0bcd\\u0baa\\u0… 证据：`examples/chatbot/.chainlit/translations/ta.json`\n- **Te**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0c38\\u0c46\\u0c1f\\u0c4d\\u0c1f\\u0c3f\\u0c02\\u0c17\\u0c4d \\u0c32\\u0c41\", \"settingsKey\": \"S\", \"APIKeys\": \"API Keys\", \"logout\": \"Logout\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0c15\\u0c4a\\u0c24\\u0c4d\\u0c24 \\u0c1a\\u0c3e\\u0c1f\\u0c4d\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0c1f\\u0c3e\\u0c38\\u0c4d\\u0c15\\u0c4d \\u0c32\\u0c3f\\u0c38\\u0c4d\\u0c1f\\u0c4d\", \"loading\": \"\\u0c32\\u0c4b\\u0c21\\u0c3f\\u0c02\\u0c17\\u0c4d...\", \"error\": \"\\u0c12\\u0c15 \\u0c26\\u0c4b\\u0c37\\u0c02 \\u0c38\\u0c02\\u0c2d\\u0c35\\u0c3f\\u0c02\\u0c1a\\u0c3f\\u0c02\\u0c26\\u0c3f\" } }, \"attachments\": { \"cancelUpload\": \"\\u0c05\\u0c2a\\u0c4d \\u0c… 证据：`examples/chatbot/.chainlit/translations/te.json`\n- **Zh Cn**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u8bbe\\u7f6e\", \"settingsKey\": \"S\", \"APIKeys\": \"API \\u5bc6\\u94a5\", \"logout\": \"\\u767b\\u51fa\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u65b0\\u5efa\\u5bf9\\u8bdd\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u4efb\\u52a1\\u5217\\u8868\", \"loading\": \"\\u52a0\\u8f7d\\u4e2d...\", \"error\": \"\\u53d1\\u751f\\u9519\\u8bef\" } }, \"attachments\": { \"cancelUpload\": \"\\u53d6\\u6d88\\u4e0a\\u4f20\", \"removeAttachment\": \"\\u79fb\\u9664\\u9644\\u4ef6\" }, \"newChatDialog\": { \"createNewChat\": \"\\u521b\\u5efa\\u65b0\\u5bf9\\u8bdd\\uff1f\", \"clearChat\": \"\\u8fd9\\u5c06\\u6e05\\u9664\\u5f53\\u524d\\u6d88\\u606f\\u5e76\\u5f00\\u59cb\\u65b0\\u7684\\u5… 证据：`examples/chatbot/.chainlit/translations/zh-CN.json`\n- **Bn**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u09b8\\u09c7\\u099f\\u09bf\\u0982\\u09b8\", \"settingsKey\": \"S\", \"APIKeys\": \"\\u098f\\u09aa\\u09bf\\u0986\\u0987 \\u0995\\u09c0\", \"logout\": \"\\u09b2\\u0997\\u0986\\u0989\\u099f\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u09a8\\u09a4\\u09c1\\u09a8 \\u0986\\u09a1\\u09cd\\u09a1\\u09be\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0995\\u09be\\u09b0\\u09cd\\u09af \\u09a4\\u09be\\u09b2\\u09bf\\u0995\\u09be\", \"loading\": \"\\u09b2\\u09cb\\u09a1\\u0964\\u0964\\u0964\", \"error\": \"\\u098f\\u0995\\u099f\\u09bf \\u09a4\\u09cd\\u09b0\\u09c1\\u099f\\u09bf \\u09b8\\u0982\\u0998\\u099f\\u09bf\\u09a4 \\u09b9\\u09af\\u09bc\\u09c7\\u099b\\u09c7\" } }, \"attachments\"… 证据：`examples/chatbot_voice/.chainlit/translations/bn.json`\n- **En Us**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"Settings\", \"settingsKey\": \"S\", \"APIKeys\": \"API Keys\", \"logout\": \"Logout\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"New Chat\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f Task List\", \"loading\": \"Loading...\", \"error\": \"An error occurred\" } }, \"attachments\": { \"cancelUpload\": \"Cancel upload\", \"removeAttachment\": \"Remove attachment\" }, \"newChatDialog\": { \"createNewChat\": \"Create new chat?\", \"clearChat\": \"This will clear the current messages and start a new chat.\", \"cancel\": \"Cancel\", \"confirm\": \"Confirm\" }, \"settingsModal\": { \"settings\": \"Settings\", \"expandMessages\": \"Expand Messages\", \"… 证据：`examples/chatbot_voice/.chainlit/translations/en-US.json`\n- **Gu**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0ab8\\u0ac1\\u0aaf\\u0acb\\u0a9c\\u0aa8\\u0acb\", \"settingsKey\": \"S\", \"APIKeys\": \"API \\u0a95\\u0ac0\\u0a93\", \"logout\": \"\\u0aac\\u0ab9\\u0abe\\u0ab0 \\u0aa8\\u0ac0\\u0a95\\u0ab3\\u0acb\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0aa8\\u0ab5\\u0acb \\u0ab8\\u0a82\\u0ab5\\u0abe\\u0aa6\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0a95\\u0abe\\u0ab0\\u0acd\\u0aaf \\u0aaf\\u0abe\\u0aa6\\u0ac0\", \"loading\": \"\\u0ab2\\u0acb\\u0aa1 \\u0a95\\u0ab0\\u0ac0 \\u0ab0\\u0ab9\\u0acd\\u0aaf\\u0abe \\u0a9b\\u0ac7...\", \"error\": \"\\u0aad\\u0ac2\\u0ab2 \\u0a89\\u0aa6\\u0acd\\u0aad\\u0ab5\\u0ac0\" } }, \"attachments\": { \"cancelUpload\": \"\\u0a85\\u0aaa\\u0ab2\\… 证据：`examples/chatbot_voice/.chainlit/translations/gu.json`\n- **He Il**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u05d4\\u05d2\\u05d3\\u05e8\\u05d5\\u05ea\", \"settingsKey\": \"S\", \"APIKeys\": \"API Keys\", \"logout\": \"\\u05d4\\u05ea\\u05e0\\u05ea\\u05e7\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u05e6'\\u05d0\\u05d8 \\u05d7\\u05d3\\u05e9\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f Task List\", \"loading\": \"\\u05d8\\u05d5\\u05e2\\u05df...\", \"error\": \"\\u05e9\\u05d2\\u05d9\\u05d0\\u05d4\" } }, \"attachments\": { \"cancelUpload\": \"\\u05d1\\u05d8\\u05dc \\u05d4\\u05e2\\u05dc\\u05d0\\u05d4\", \"removeAttachment\": \"\\u05d4\\u05e1\\u05e8 \\u05e7\\u05d5\\u05d1\\u05e5 \\u05de\\u05e6\\u05d5\\u05e8\\u05e3\" }, \"newChatDialog\": { \"createNewChat\": \"\\u05e6\\u05d5\\u… 证据：`examples/chatbot_voice/.chainlit/translations/he-IL.json`\n- **Hi**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0938\\u0947\\u091f\\u093f\\u0902\\u0917\\u094d\\u0938\", \"settingsKey\": \"\\u0926\\u0915\\u094d\\u0937\\u093f\\u0923\\u0940\", \"APIKeys\": \"\\u090f\\u092a\\u0940\\u0906\\u0908 \\u0915\\u0941\\u0902\\u091c\\u0940\", \"logout\": \"\\u0932\\u0949\\u0917\\u0906\\u0909\\u091f\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0928\\u0908 \\u091a\\u0948\\u091f\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0915\\u093e\\u0930\\u094d\\u092f \\u0938\\u0942\\u091a\\u0940\", \"loading\": \"\\u0932\\u094b\\u0921\\u0964\\u0964\\u0964\", \"error\": \"\\u0915\\u094b\\u0908 \\u0924\\u094d\\u0930\\u0941\\u091f\\u093f \\u0909\\u0924\\u094d\\u092a\\u0928\\u094d\\u0928 \\u0939\\u0941\\u0… 证据：`examples/chatbot_voice/.chainlit/translations/hi.json`\n- **Kn**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0cb8\\u0cc6\\u0c9f\\u0ccd\\u0c9f\\u0cbf\\u0c82\\u0c97\\u0ccd \\u0c97\\u0cb3\\u0cc1\", \"settingsKey\": \"S\", \"APIKeys\": \"API \\u0c95\\u0cc0\\u0cb2\\u0cbf\\u0c97\\u0cb3\\u0cc1\", \"logout\": \"\\u0cb2\\u0cbe\\u0c97\\u0ccd \\u0c94\\u0c9f\\u0ccd\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0cb9\\u0cca\\u0cb8 \\u0c9a\\u0cbe\\u0c9f\\u0ccd\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0c95\\u0cbe\\u0cb0\\u0ccd\\u0caf \\u0caa\\u0c9f\\u0ccd\\u0c9f\\u0cbf\", \"loading\": \"\\u0cb2\\u0ccb\\u0ca1\\u0ccd \\u0c86\\u0c97\\u0cc1\\u0ca4\\u0ccd\\u0ca4\\u0cbf\\u0ca6\\u0cc6...\", \"error\": \"\\u0ca6\\u0ccb\\u0cb7 \\u0cb8\\u0c82\\u0cad\\u0cb5\\u0cbf\\u0cb8\\u0cbf\\u0ca6\\u0cc6\"… 证据：`examples/chatbot_voice/.chainlit/translations/kn.json`\n- **Ml**（structured_config）：{ \"components\": { \"atoms\": { \"buttons\": { \"userButton\": { \"menu\": { \"settings\": \"\\u0d15\\u0d4d\\u0d30\\u0d2e\\u0d40\\u0d15\\u0d30\\u0d23\\u0d19\\u0d4d\\u0d19\\u0d7e\", \"settingsKey\": \"S\", \"APIKeys\": \"API \\u0d15\\u0d40\\u0d15\\u0d7e\", \"logout\": \"\\u0d32\\u0d4b\\u0d17\\u0d4b\\u0d1f\\u0d4d\\u0d1f\\u0d4d\" } } } }, \"molecules\": { \"newChatButton\": { \"newChat\": \"\\u0d2a\\u0d41\\u0d24\\u0d3f\\u0d2f \\u0d1a\\u0d3e\\u0d31\\u0d4d\\u0d31\\u0d4d\" }, \"tasklist\": { \"TaskList\": { \"title\": \"\\ud83d\\uddd2\\ufe0f \\u0d1f\\u0d3e\\u0d38\\u0d4d\\u0d15\\u0d4d \\u0d32\\u0d3f\\u0d38\\u0d4d\\u0d31\\u0d4d\\u0d31\\u0d4d\", \"loading\": \"\\u0d32\\u0d4b\\u0d21\\u0d3f\\u0d02\\u0d17\\u0d4d...\", \"error\": \"\\u0d12\\u0d30\\u0d41 \\u0d2a\\u0d3f\\u0d36\\u0d15\\u0d4d \\u0d38\\u0d02\\u0d2d\\u0d35\\u0… 证据：`examples/chatbot_voice/.chainlit/translations/ml.json`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/README.md`, `README.md`, `core/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/README.md`, `README.md`, `core/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目概述**：importance `high`\n - source_paths: README.md, core/README.md, core/quivr_core/__init__.py\n- **快速入门指南**：importance `high`\n - source_paths: examples/simple_question/simple_question.py, examples/simple_question/simple_question_streaming.py, examples/chatbot/main.py\n- **系统架构**：importance `high`\n - source_paths: core/quivr_core/brain/brain.py, core/quivr_core/rag/quivr_rag.py, core/quivr_core/rag/quivr_rag_langgraph.py, core/quivr_core/config.py\n- **RAG 处理流程**：importance `high`\n - source_paths: core/quivr_core/rag/quivr_rag.py, core/quivr_core/rag/quivr_rag_langgraph.py, core/quivr_core/rag/prompts.py, core/quivr_core/rag/entities/chat.py, core/quivr_core/rag/entities/models.py\n- **Brain 核心概念**：importance `high`\n - source_paths: core/quivr_core/brain/brain.py, core/quivr_core/brain/brain_defaults.py, core/quivr_core/brain/info.py, core/quivr_core/brain/serialization.py\n- **文件处理系统**：importance `high`\n - source_paths: core/quivr_core/processor/processor_base.py, core/quivr_core/processor/registry.py, core/quivr_core/processor/splitter.py, core/quivr_core/processor/implementations/default.py, core/quivr_core/processor/implementations/megaparse_processor.py\n- **存储系统**：importance `medium`\n - source_paths: core/quivr_core/storage/storage_base.py, core/quivr_core/storage/local_storage.py, core/quivr_core/storage/file.py, examples/custom_storage.md\n- **LLM 集成**：importance `high`\n - source_paths: core/quivr_core/llm/llm_endpoint.py, core/quivr_core/language/models.py, core/quivr_core/language/utils.py, core/quivr_core/rag/entities/config.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `947a785415c6c35ab2ae8157222b4720b0710b4d`\n- inspected_files: `README.md`, `docs/pyproject.toml`, `docs/mkdocs.yml`, `docs/README.md`, `docs/docs/index.md`, `docs/docs/quickstart.md`, `docs/src/docs/__init__.py`, `docs/docs/vectorstores/index.md`, `docs/docs/vectorstores/pgvector.md`, `docs/docs/vectorstores/faiss.md`, `docs/docs/brain/index.md`, `docs/docs/brain/brain.md`, `docs/docs/brain/chat.md`, `docs/docs/parsers/index.md`, `docs/docs/parsers/megaparse.md`, `docs/docs/parsers/simple.md`, `docs/docs/config/index.md`, `docs/docs/config/base_config.md`, `docs/docs/config/config.md`, `docs/docs/storage/index.md`\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: 来源证据：EU AI Act Compliance Scan Results — Sharing Findings for Feedback\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：EU AI Act Compliance Scan Results — Sharing Findings for Feedback\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_46118108af95480ba852109be6e2c66a | https://github.com/QuivrHQ/quivr/issues/3667 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：[Bug]:\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]:\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ff260ca3ab5247679b2ded201ec21e24 | https://github.com/QuivrHQ/quivr/issues/2004 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Integration idea: Screenpipe for screen/audio context\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Integration idea: Screenpipe for screen/audio context\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3a7f345691d04bbea72b03858746645e | https://github.com/QuivrHQ/quivr/issues/3658 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_e3091b23b6184dffb982e0cc494134fd | https://github.com/QuivrHQ/quivr/issues/3650 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 能力判断依赖假设\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:640079149 | https://github.com/QuivrHQ/quivr | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：The garbage collector is trying to clean up non-checked-in connection >, which will…\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e6fdde799a2b4f53806121190979025a | https://github.com/QuivrHQ/quivr/issues/3654 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：core: v0.0.25\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.25\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7c6096fb5a6442c7b53068a8dd8e2c78 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.25 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：core: v0.0.29\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.29\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7eeeeb626a10476e820fcd651727a55a | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.29 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：core: v0.0.33\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.33\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_d7a735cb41bc44f2abeb148d689f1320 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.33 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：core: v0.0.24\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：core: v0.0.24\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_5272fe70cda24220a5aeb994ad06819e | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.24 | 来源类型 github_release 暴露的待验证使用条件。\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项目：QuivrHQ/quivr\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- 来源证据：EU AI Act Compliance Scan Results — Sharing Findings for Feedback（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：[Bug]:（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Integration idea: Screenpipe for screen/audio context（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 能力判断依赖假设（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/QuivrHQ/quivr 项目说明书\n\n生成时间: 2026-05-21 18:53:42 UTC\n\n## 目录\n\n- [项目概述](#page-overview)\n- [快速入门指南](#page-quickstart)\n- [系统架构](#page-architecture)\n- [RAG 处理流程](#page-rag-flow)\n- [Brain 核心概念](#page-brain)\n- [文件处理系统](#page-processor)\n- [存储系统](#page-storage)\n- [LLM 集成](#page-llm)\n- [工具扩展系统](#page-tools)\n- [工作流配置](#page-workflow)\n\n\n\n## 项目概述\n\n### 相关页面\n\n相关主题：[快速入门指南](#page-quickstart), [系统架构](#page-architecture)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/QuivrHQ/quivr/blob/main/README.md)\n- [core/README.md](https://github.com/QuivrHQ/quivr/blob/main/core/README.md)\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/processor/processor_base.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/processor_base.py)\n- [examples/simple_question/simple_question.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question.py)\n- [examples/pdf_parsing_tika.py](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py)\n
\n\n# 项目概述\n\n## 项目简介\n\nQuivr 是一个开源的个人第二大脑（Second Brain）项目，利用生成式人工智能（Generative AI）技术帮助用户构建智能知识助手。该项目旨在为开发者提供一套快速、高效且可定制的检索增强生成（RAG）解决方案，使开发者能够专注于产品开发，而无需深入研究 RAG 技术的底层细节。\n\n资料来源：[README.md:1-15]()\n\n### 核心定位\n\nQuivr 的核心价值主张在于：\n\n- **开箱即用的 RAG 方案**：提供经过优化的检索增强生成工作流，开箱即用\n- **多模型支持**：兼容 OpenAI、Anthropic、Mistral、Gemma 等主流大语言模型\n- **任意文件类型支持**：支持 PDF、TXT、Markdown 等常见格式，并允许自定义解析器\n- **完全可定制**：支持添加互联网搜索、工具扩展等高级功能\n\n资料来源：[README.md:25-35]()\n\n## 技术架构\n\n### 整体架构\n\nQuivr 采用模块化架构设计，主要包含以下核心组件：\n\n```mermaid\ngraph TD\n A[用户查询] --> B[Brain 核心类]\n B --> C[RAG 工作流引擎]\n C --> D[检索模块]\n C --> E[重排序模块]\n C --> F[生成模块]\n D --> G[向量数据库]\n E --> G\n F --> H[LLM 大语言模型]\n G --> D\n```\n\n### 核心模块说明\n\n| 模块名称 | 功能描述 | 关键文件 |\n|---------|---------|---------|\n| Brain | 核心管理类，负责文件处理和查询编排 | `quivr_core/brain/brain.py` |\n| RAG | 检索增强生成引擎，处理检索和生成逻辑 | `quivr_core/rag/quivr_rag.py` |\n| Processor | 文件解析器，处理各种文件格式 | `quivr_core/processor/processor_base.py` |\n| Embeddings | 向量化模块，将文本转换为向量 | 配置可指定 |\n| LLM Endpoint | 大语言模型接口，支持多种模型 | `quivr_core/llm/llm_endpoint.py` |\n\n资料来源：[core/README.md:1-15]()\n\n## 快速入门\n\n### 环境要求\n\n| 要求 | 最低版本 |\n|-----|---------|\n| Python | 3.10+ |\n| pip | 最新版本 |\n\n资料来源：[README.md:50-55]()\n\n### 安装方式\n\n通过 pip 安装 quivr-core 核心包：\n\n```bash\npip install quivr-core\n```\n\n资料来源：[README.md:30-35]()\n\n### 5 行代码创建 RAG\n\n以下示例展示了如何使用 Quivr 构建一个简单的问答系统：\n\n```python\nimport tempfile\nfrom quivr_core import Brain\n\nif __name__ == \"__main__\":\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".txt\") as temp_file:\n temp_file.write(\"Gold is a liquid of blue-like colour.\")\n temp_file.flush()\n\n brain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[temp_file.name],\n )\n\n answer = brain.ask(\"what is gold? answer in french\")\n print(\"answer:\", answer)\n```\n\n资料来源：[README.md:38-55]()\n\n## Brain 核心类\n\n### 核心功能\n\n`Brain` 类是 Quivr 的核心入口点，封装了文件处理、向量存储和问答功能。该类提供了以下关键方法：\n\n| 方法名 | 功能描述 | 返回类型 |\n|-------|---------|---------|\n| `from_files` | 从文件创建 Brain 实例 | `Brain` |\n| `from_langchain_documents` | 从 LangChain 文档创建 Brain | `Brain` |\n| `asearch` | 异步搜索相关文档 | `list[SearchResult]` |\n| `ask` | 提问并获取回答 | `RAGResponse` |\n\n资料来源：[core/quivr_core/brain/brain.py:1-80]()\n\n### 文件处理流程\n\n```mermaid\ngraph LR\n A[上传文件] --> B[Processor 解析]\n B --> C[分块处理]\n C --> D[元数据提取]\n D --> E[语言检测]\n E --> F[向量数据库存储]\n```\n\n### 元数据处理\n\n每个文档块在处理时都会附加丰富的元数据信息：\n\n| 元数据字段 | 来源 | 说明 |\n|-----------|-----|------|\n| `chunk_index` | 自动生成 | 文档块索引 |\n| `quivr_core_version` | 系统信息 | Quivr 版本号 |\n| `language` | 自动检测 | 文档语言 |\n| `original_file_name` | 文件属性 | 原始文件名 |\n\n资料来源：[core/quivr_core/processor/processor_base.py:15-35]()\n\n## RAG 工作流配置\n\n### 工作流节点\n\nQuivr 支持通过 YAML 配置文件定义 RAG 工作流，包含以下标准节点：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"retrieve\"]\n - name: \"retrieve\"\n edges: [\"generate_rag\"]\n - name: \"generate_rag\"\n edges: [\"END\"]\n```\n\n资料来源：[README.md:70-85]()\n\n### 配置参数\n\n| 配置类别 | 参数名 | 说明 | 默认值 |\n|---------|-------|------|-------|\n| 历史记录 | `max_history` | 最大历史对话轮次 | 10 |\n| 重排序 | `supplier` | 重排序模型供应商 | cohere |\n| 重排序 | `model` | 重排序模型名称 | rerank-multilingual-v3.0 |\n| 重排序 | `top_n` | 返回的重排序结果数 | 5 |\n| LLM | `max_input_tokens` | 最大输入 token 数 | 4000 |\n| LLM | `temperature` | 生成温度参数 | 0.7 |\n\n资料来源：[README.md:85-100]()\n\n## 支持的文件格式\n\nQuivr 通过处理器架构支持多种文件格式：\n\n| 文件类型 | 支持状态 | 说明 |\n|---------|---------|------|\n| PDF | ✅ 完整支持 | 通过 Megaparse 集成 |\n| TXT | ✅ 完整支持 | 文本文件直接处理 |\n| Markdown | ✅ 完整支持 | 支持 Markdown 语法 |\n| 自定义 | ✅ 可扩展 | 支持添加自定义解析器 |\n\n资料来源：[README.md:35-40]()\n\n## 集成与扩展\n\n### 大语言模型集成\n\nQuivr 支持多种大语言模型供应商：\n\n| 供应商 | 支持状态 | 配置方式 |\n|-------|---------|---------|\n| OpenAI | ✅ 支持 | 设置 `OPENAI_API_KEY` |\n| Anthropic | ✅ 支持 | 设置 API Key |\n| Mistral | ✅ 支持 | 设置 API Key |\n| Ollama | ✅ 支持 | 本地模型配置 |\n| Gemma | ✅ 支持 | 通过 API 或本地部署 |\n\n资料来源：[README.md:20-25]()\n\n### 外部服务集成\n\n- **Megaparse**：用于大规模文件解析和 ingestion\n- **向量数据库**：支持可配置的向量存储后端\n\n资料来源：[README.md:38-42]()\n\n## 应用示例\n\n### 基础问答机器人\n\n使用 Chainlit 框架构建的文本问答机器人架构：\n\n```mermaid\ngraph TD\n A[用户上传文件] --> B[Chainlit 前端]\n B --> C[Quivr Brain 处理]\n C --> D[向量检索]\n D --> E[LLM 生成回答]\n E --> B\n```\n\n核心代码示例：\n\n```python\nfrom quivr_core import Brain\n\nbrain = Brain.from_files(\n name=\"my smart brain\",\n file_paths=[\"./my_first_doc.pdf\", \"./my_second_doc.txt\"],\n)\n\nanswer = brain.ask(question)\n```\n\n资料来源：[examples/simple_question/simple_question.py:1-20]()\n\n### 语音交互应用\n\nquivr-whisper 示例展示了如何构建语音交互系统：\n\n1. 用户录制语音问题\n2. 通过 Whisper 转录为文本\n3. 调用 Quivr API 获取回答\n4. 使用 TTS 将回答合成语音并播放\n\n资料来源：[examples/quivr-whisper/README.md:1-25]()\n\n## 项目结构\n\n```\nquivr/\n├── README.md # 主项目文档\n├── core/ # 核心包目录\n│ ├── README.md # quivr-core 说明\n│ └── quivr_core/\n│ ├── brain/ # Brain 核心类\n│ ├── rag/ # RAG 工作流\n│ ├── processor/ # 文件处理器\n│ └── llm/ # LLM 接口封装\n├── examples/ # 示例代码\n│ ├── chatbot/ # Chainlit 聊天机器人\n│ ├── chatbot_voice/ # 语音聊天机器人\n│ ├── simple_question/ # 简单问答示例\n│ └── pdf_parsing_tika.py # PDF 解析示例\n```\n\n资料来源：[core/README.md:1-15]()\n\n## 技术栈总结\n\n| 技术领域 | 使用的技术 |\n|---------|-----------|\n| 核心框架 | Python 3.10+ |\n| 向量检索 | 可配置向量数据库 |\n| 大语言模型 | OpenAI, Anthropic, Mistral, Ollama |\n| Web 框架 | Flask, Chainlit |\n| 语音处理 | Whisper |\n| 文件解析 | Megaparse |\n\n## 下一步\n\n- 访问 [官方文档](https://core.quivr.com/) 了解更多高级功能\n- 查看 [示例代码](./examples/) 学习具体用法\n- 参与 [贡献指南](https://github.com/QuivrHQ/quivr/blob/main/CONTRIBUTING.md) 加入社区\n\n---\n\n\n\n## 快速入门指南\n\n### 相关页面\n\n相关主题：[项目概述](#page-overview), [Brain 核心概念](#page-brain)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [examples/simple_question/simple_question.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question.py)\n- [examples/simple_question/simple_question_streaming.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question_streaming.py)\n- [examples/chatbot/main.py](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot/main.py)\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n- [core/README.md](https://github.com/QuivrHQ/quivr/blob/main/core/README.md)\n
\n\n# 快速入门指南\n\n## 概述\n\nQuivr-core 是 Quivr 项目的核心 RAG（检索增强生成）引擎，专注于让开发者能够快速构建基于文档的智能问答系统。本指南将帮助您从零开始，在 5 行代码内创建一个功能完整的 RAG 应用。\n\n## 安装\n\n使用 pip 安装 quivr-core 包：\n\n```bash\npip install quivr-core\n```\n\n资料来源：[core/README.md](https://github.com/QuivrHQ/quivr/blob/main/core/README.md)\n\n## 核心概念\n\n### Brain（大脑）\n\n`Brain` 是 Quivr-core 的核心类，负责管理文档处理、向量存储和问答逻辑。\n\n```mermaid\ngraph TD\n A[用户提问] --> B[Brain.ask]\n B --> C[检索相关文档]\n C --> D[构建提示词]\n D --> E[调用LLM]\n E --> F[返回答案]\n```\n\n## 基本用法\n\n### 创建 Brain 并提问\n\n以下示例演示了最基础的 RAG 用法：\n\n```python\nimport tempfile\nfrom quivr_core import Brain\n\nwith tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".txt\") as temp_file:\n temp_file.write(\"Gold is a liquid of blue-like colour.\")\n temp_file.flush()\n\n brain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[temp_file.name],\n )\n\n answer = brain.ask(\n question=\"what is gold? answer in french\",\n run_id=None # 需要传入UUID\n )\n print(\"answer:\", answer.answer)\n```\n\n资料来源：[examples/simple_question/simple_question.py:1-20](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question.py)\n\n### 异步提问方式\n\n`Brain.ask` 方法存在同步版本和异步版本：\n\n| 方法 | 描述 | 返回类型 |\n|------|------|----------|\n| `ask()` | 同步方法，等待完整回答 | `ParsedRAGResponse` |\n| `ask_streaming()` | 异步流式方法，逐块返回 | `AsyncGenerator[ParsedRAGChunkResponse]` |\n\n异步方法签名：\n\n```python\nasync def ask_streaming(\n self,\n run_id: UUID,\n question: str,\n system_prompt: str | None = None,\n retrieval_config: RetrievalConfig | None = None,\n rag_pipeline: Type[Union[QuivrQARAG, QuivrQARAGLangGraph]] | None = None,\n list_files: list[QuivrKnowledge] | None = None,\n chat_history: ChatHistory | None = None,\n) -> AsyncGenerator[ParsedRAGChunkResponse, None]\n```\n\n资料来源：[core/quivr_core/brain/brain.py:检索配置](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n\n### 流式响应示例\n\n```python\nimport asyncio\nfrom uuid import uuid4\n\nasync def streaming_example():\n brain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[\"./documents.pdf\"]\n )\n \n async for chunk in brain.ask_streaming(\n run_id=uuid4(),\n question=\"Summarize the document\"\n ):\n if not chunk.last_chunk:\n print(chunk.answer, end=\"\", flush=True)\n```\n\n## 环境配置\n\n### API Key 设置\n\n在使用 LLM 提供商之前，需要配置 API Key：\n\n```python\nimport os\nos.environ[\"OPENAI_API_KEY\"] = \"your-api-key-here\"\n```\n\nQuivr 支持的 LLM 提供商：\n\n| 提供商 | 环境变量 |\n|--------|----------|\n| OpenAI | `OPENAI_API_KEY` |\n| Anthropic | `ANTHROPIC_API_KEY` |\n| Mistral | `MISTRAL_API_KEY` |\n| Ollama（本地） | 需配置 `llm_base_url` |\n\n## 进阶配置\n\n### 自定义检索配置\n\n通过 `RetrievalConfig` 可以自定义检索行为：\n\n```python\nfrom quivr_core.config import RetrievalConfig\n\nconfig = RetrievalConfig(\n max_history=10,\n prompt=\"You are a helpful assistant.\",\n llm_config=LLMEndpointConfig(\n model=\"gpt-4\",\n temperature=0.7,\n max_input_tokens=4000\n )\n)\n\nanswer = brain.ask(\n run_id=uuid4(),\n question=\"your question\",\n retrieval_config=config\n)\n```\n\n### 使用 Chainlit 构建对话界面\n\n创建交互式聊天机器人的完整示例：\n\n```python\nimport chainlit as cl\nfrom uuid import uuid4\nfrom quivr_core import Brain\n\n@cl.on_message\nasync def main(message: cl.Message):\n # 获取或创建 brain\n brain = await cl.make_async(Brain.from_files)(\n name=\"chatbot_brain\",\n file_paths=[\"./data.txt\"]\n )\n \n msg = cl.Message(content=\"\")\n async for response in brain.ask_streaming(\n run_id=uuid4(),\n question=message.content\n ):\n if not response.last_chunk:\n await msg.stream_token(response.answer)\n \n await msg.send()\n```\n\n资料来源：[examples/chatbot/main.py](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot/main.py)\n\n## 工作流程\n\n```mermaid\ngraph LR\n A[文件] --> B[文件处理器]\n B --> C[文本分块]\n C --> D[向量化]\n D --> E[向量数据库]\n E --> F[检索]\n F --> G[LLM生成]\n G --> H[返回答案]\n```\n\n## 支持的文件格式\n\nQuivr-core 通过内置处理器支持多种文件格式：\n\n| 格式 | 处理器 |\n|------|--------|\n| PDF | `UnstructuredPDFLoader` |\n| TXT | `TextLoader` |\n| CSV | `CSVLoader` |\n| DOCX | `Docx2txtLoader` |\n| Markdown | `UnstructuredMarkdownLoader` |\n| HTML | `UnstructuredHTMLLoader` |\n| Excel | `UnstructuredExcelLoader` |\n| PowerPoint | `UnstructuredPowerPointLoader` |\n| Python | `PythonLoader` |\n\n## 下一步\n\n- 查看 [Workflow 配置文档](https://github.com/QuivrHQ/quivr/blob/main/README.md) 了解高级检索策略\n- 参考 [LangChain 集成](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py) 实现自定义处理流程\n- 探索 [语音聊天示例](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot_voice/README.md) 构建多模态应用\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[RAG 处理流程](#page-rag-flow), [Brain 核心概念](#page-brain)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/rag/quivr_rag_langgraph.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag_langgraph.py)\n- [core/quivr_core/config.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/config.py)\n- [core/quivr_core/storage/local_storage.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/local_storage.py)\n
\n\n# 系统架构\n\n## 概述\n\nQuivr 是一个基于生成式 AI 的个人第二大脑框架，其核心库 `quivr-core` 提供了一套完整的 RAG（检索增强生成）系统。该系统通过模块化设计，支持多种文件格式处理、灵活的 LLM 配置、可定制的检索策略以及持久化存储能力。资料来源：[README.md:1-30]()\n\n## 核心架构图\n\n```mermaid\ngraph TD\n subgraph 用户层\n A[用户查询] --> B[Brain.ask]\n end\n\n subgraph 核心层\n B --> C[RetrievalConfig]\n C --> D[QuivrQARAGLangGraph]\n D --> E[LLMEndpoint]\n D --> F[VectorStore]\n end\n\n subgraph 数据层\n F --> G[Chroma/FAISS/Pgvector]\n G --> H[Embeddings]\n end\n\n subgraph 存储层\n I[LocalStorage] --> J[Brain持久化]\n end\n\n style 用户层 fill:#e1f5fe\n style 核心层 fill:#fff3e0\n style 数据层 fill:#e8f5e9\n style 存储层 fill:#fce4ec\n```\n\n## 核心组件\n\n### Brain 类\n\n`Brain` 是整个系统的核心入口类，负责管理文件处理、向量存储、检索配置和 LLM 调用。资料来源：[core/quivr_core/brain/brain.py:1-100]()\n\n```mermaid\nclassDiagram\n class Brain {\n +id: UUID\n +name: str\n +llm: LLMEndpoint\n +embedder: Embeddings\n +vector_db: VectorStore\n +storage: StorageInterface\n +from_files()\n +afrom_files()\n +from_langchain_documents()\n +ask()\n +asearch()\n +save()\n +load()\n }\n```\n\n**Brain 核心属性表：**\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | `UUID` | 脑实例的唯一标识符 |\n| `name` | `str` | 脑实例的名称 |\n| `llm` | `LLMEndpoint` | 大语言模型端点 |\n| `embedder` | `Embeddings` | 嵌入模型用于向量化和检索 |\n| `vector_db` | `VectorStore` | 向量数据库实例 |\n| `storage` | `StorageInterface` | 文件存储接口 |\n\n资料来源：[core/quivr_core/brain/brain.py:50-60]()\n\n### RAG 引擎\n\nQuivr 提供两种 RAG 实现：基于 LangChain 的传统 RAG 和基于 LangGraph 的工作流 RAG。资料来源：[core/quivr_core/rag/quivr_rag.py:1-50]()\n\n```mermaid\ngraph LR\n A[用户问题] --> B[检索阶段]\n B --> C[重写查询]\n C --> D[历史过滤]\n D --> E[向量检索]\n E --> F[生成阶段]\n F --> G[LLM响应]\n```\n\n**QuivrQARAGLangGraph 工作流节点：**\n\n| 节点名称 | 功能 | 说明 |\n|----------|------|------|\n| `START` | 起点 | 工作流起始节点 |\n| `filter_history` | 历史过滤 | 过滤对话历史中的相关内容 |\n| `rewrite` | 查询重写 | 使用 LLM 优化用户查询 |\n| `generate` | 答案生成 | 基于检索结果生成最终答案 |\n\n资料来源：[core/quivr_core/rag/quivr_rag_langgraph.py:1-80]()\n\n### 配置系统\n\n配置系统通过 `RetrievalConfig` 类统一管理 RAG 流程的各个环节。资料来源：[core/quivr_core/config.py:1-100]()\n\n```python\nretrieval_config = RetrievalConfig.from_yaml(\"./basic_rag_workflow.yaml\")\n```\n\n**RetrievalConfig 核心参数：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `llm_config` | `LLMEndpointConfig` | 默认LLM | 语言模型配置 |\n| `temperature` | `float` | `0.7` | LLM 生成温度 |\n| `n_results` | `int` | `5` | 检索结果数量 |\n| `max_tokens` | `int` | `None` | 最大生成 token 数 |\n\n资料来源：[core/quivr_core/config.py:30-50]()\n\n## 数据流程\n\n### 文件处理流程\n\n```mermaid\ngraph TD\n A[文件上传] --> B[FileValidator]\n B --> C[FileProcessor]\n C --> D[LangChain Documents]\n D --> E[Embedder 向量化]\n E --> F[VectorStore 存储]\n F --> G[Brain 索引完成]\n```\n\n### 问答流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant B as Brain\n participant R as QuivrQARAGLangGraph\n participant V as VectorStore\n participant L as LLM\n\n U->>B: ask(question)\n B->>R: answer_astream()\n R->>V: asearch(query)\n V-->>R: 相关文档块\n R->>L: generate(上下文)\n L-->>R: 流式响应\n R-->>B: ParsedRAGChunkResponse\n B-->>U: 返回答案\n```\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:80-120]()\n\n## 存储系统\n\n### LocalStorage 实现\n\nLocalStorage 提供了本地文件系统存储能力，支持文件去重（基于 SHA-1 哈希）。资料来源：[core/quivr_core/storage/local_storage.py:1-80]()\n\n```mermaid\ngraph TD\n A[上传文件] --> B{计算SHA-1}\n B --> C{文件存在?}\n C -->|是| D{exists_ok?}\n C -->|否| E[复制/链接文件]\n D -->|True| E\n D -->|False| F[抛出FileExistsError]\n E --> G[更新文件列表]\n```\n\n**LocalStorage 核心方法：**\n\n| 方法 | 参数 | 返回值 | 说明 |\n|------|------|--------|------|\n| `upload_file` | `file: QuivrFile, exists_ok: bool` | `None` | 上传文件到本地存储 |\n| `get_files` | 无 | `list[QuivrFile]` | 获取所有存储文件 |\n| `remove_file` | `file_id: UUID` | `None` | 移除指定文件 |\n| `load` | `config: LocalStorageConfig` | `Self` | 从配置加载存储实例 |\n\n资料来源：[core/quivr_core/storage/local_storage.py:50-70]()\n\n## 持久化与加载\n\n### Brain 保存与加载\n\nBrain 实例支持通过 `save()` 和 `load()` 方法进行持久化。资料来源：[examples/save_load_brain.py:1-25]()\n\n```python\n# 保存 Brain\nsave_path = await brain.save(\"/home/user/.local/quivr\")\n\n# 加载 Brain\nbrain_loaded = Brain.load(save_path)\n```\n\n**保存流程图：**\n\n```mermaid\ngraph LR\n A[Brain实例] --> B[序列化元数据]\n A --> C[序列化VectorDB]\n A --> D[序列化LLM配置]\n B --> E[写入文件系统]\n C --> E\n D --> E\n E --> F[返回保存路径]\n```\n\n## LLM 配置\n\nQuivr 支持多种 LLM 提供商，包括 OpenAI、Anthropic、Mistral 以及本地 Ollama 模型。资料来源：[core/quivr_core/llm/llm_endpoint.py:1-50]()\n\n```python\nfrom quivr_core.llm.llm_endpoint import LLMEndpoint\nfrom quivr_core.rag.entities.config import LLMEndpointConfig\n\nllm = LLMEndpoint.from_config(\n config=LLMEndpointConfig(\n model=\"gpt-4\",\n llm_base_url=\"https://api.openai.com/v1\",\n api_key=os.environ[\"OPENAI_API_KEY\"]\n )\n)\n```\n\n## 工作流配置\n\n通过 YAML 配置文件可以自定义 RAG 工作流节点和边。资料来源：[README.md:40-80]()\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"generate\"]\n - name: \"generate\"\n edges: []\n```\n\n## 模块依赖关系\n\n```mermaid\ngraph TD\n subgraph quivr_core\n A[Brain] --> B[RAG模块]\n A --> C[存储模块]\n A --> D[LLM模块]\n B --> E[配置模块]\n E --> F[向量存储]\n D --> F\n end\n\n subgraph 外部依赖\n G[LangChain]\n H[Chroma/FAISS]\n I[OpenAI API]\n end\n\n F --> H\n D --> G\n B --> G\n G --> I\n```\n\n## 关键设计决策\n\n| 设计点 | 说明 | 优势 |\n|--------|------|------|\n| 模块化 RAG | RAG 逻辑与 Brain 分离 | 便于测试和复用 |\n| LangGraph 工作流 | 使用状态图管理 RAG 流程 | 灵活的条件分支和并行处理 |\n| 异步优先 | 主要方法提供 async 版本 | 高并发场景性能优化 |\n| 向量存储抽象 | 统一 VectorStore 接口 | 支持多种后端切换 |\n| 配置驱动 | YAML 配置工作流 | 无需代码修改即可调整流程 |\n\n## 总结\n\nQuivr 的系统架构采用分层设计，核心层由 Brain 类统一调度，通过 RetrievalConfig 配置检索策略，借助 LangGraph 工作流实现灵活的 RAG 流程。向量存储层支持多种后端，存储层提供本地持久化能力，整体设计注重可扩展性和模块化，使开发者能够根据需求自由组合各组件。\n\n---\n\n\n\n## RAG 处理流程\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [LLM 集成](#page-llm)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/rag/quivr_rag_langgraph.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag_langgraph.py)\n- [core/quivr_core/rag/prompts.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/prompts.py)\n- [core/quivr_core/rag/entities/chat.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/chat.py)\n- [core/quivr_core/rag/entities/models.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/models.py)\n
\n\n# RAG 处理流程\n\n## 概述\n\nQuivr 的 RAG（检索增强生成）处理流程是核心功能模块，负责将用户查询与知识库中的文档相结合，生成准确、上下文相关的回答。该流程整合了文档检索、查询重写、历史过滤和流式响应生成等多个环节，形成一个完整的问答管道。\n\nRAG 流程的主要职责包括：从向量数据库中检索相关文档、对聊天历史进行过滤处理、将检索结果与用户查询组合成提示词、调用大语言模型生成回答，以及支持流式输出和元数据返回。资料来源：[core/quivr_core/rag/quivr_rag.py:1-50]()\n\n## 核心组件架构\n\n### 组件关系图\n\n```mermaid\ngraph TD\n A[用户查询] --> B[ChatHistory 聊天历史]\n B --> C[filter_history 过滤历史]\n C --> D[检索配置 RetrievalConfig]\n D --> E[向量存储 VectorStore]\n E --> F[Reranker 文档重排序]\n F --> G[LLMEndpoint 大语言模型]\n G --> H[流式响应 ParsedRAGChunkResponse]\n H --> I[最终回答]\n \n J[Brain 脑实例] --> E\n K[Embeddings 嵌入模型] --> E\n```\n\n### 核心类说明\n\n| 组件名称 | 文件位置 | 功能描述 |\n|---------|---------|---------|\n| `QuivrQARAG` | quivr_rag.py | RAG 主类，整合检索和生成流程 |\n| `IdempotentCompressor` | quivr_rag.py | 文档压缩器，保持原文档不变 |\n| `LLMEndpoint` | llm_endpoint.py | 大语言模型端点封装 |\n| `RetrievalConfig` | entities/config.py | 检索配置管理 |\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:44-60]()\n\n## 处理流程详解\n\n### 1. 聊天历史过滤\n\n在处理用户查询前，系统首先对聊天历史进行过滤，移除与当前问题无关的历史消息以提高检索效率。\n\n```python\ndef filter_history(\n self,\n chat_history: ChatHistory,\n):\n \"\"\"\n Filter out the chat history to only include the messages \n that are relevant to the current question\n \"\"\"\n```\n\n该方法接收 `ChatHistory` 对象作为输入，通过分析历史消息的相关性，返回过滤后的消息列表。资料来源：[core/quivr_core/rag/quivr_rag.py:68-76]()\n\n### 2. 文档检索配置\n\n检索配置定义了 RAG 流程的行为参数，包括：\n\n| 配置项 | 类型 | 说明 |\n|-------|------|-----|\n| `n_results` | int | 检索返回的结果数量，默认值为 5 |\n| `filter` | Callable/Dict | 检索过滤器条件 |\n| `fetch_n_neighbors` | int | 邻近检索数量，默认 20 |\n| `temperature` | float | LLM 温度参数，控制创造性 |\n\n资料来源：[core/quivr_core/brain/brain.py:80-95]()\n\n### 3. 向量存储检索\n\n`Brain` 类提供了 `asearch` 异步搜索方法，用于从向量数据库中检索相关文档：\n\n```python\nasync def asearch(\n self,\n query: str | Document,\n n_results: int = 5,\n filter: Callable | Dict[str, Any] | None = None,\n fetch_n_neighbors: int = 20,\n) -> list[SearchResult]:\n```\n\n该方法返回 `SearchResult` 对象列表，每个结果包含文档内容和元数据。资料来源：[core/quivr_core/brain/brain.py:80-95]()\n\n### 4. 提示词构建\n\n检索到的文档与用户查询一起被注入到提示词模板中：\n\n```python\nuser_prompt_template = \"\"\"\nHere is information about the user that can help you to answer:\n\n{user_metadata}\n\n\nHere are metadata on the current ticket:\n\n{ticket_metadata}\n\n\nHere are the most relevant similar tickets:\n\n{similar_tickets}\n\n\nHere is the client question:\n\n{client_query}\n\n\"\"\"\n```\n\n提示词模板支持以下占位符替换：\n\n- `{user_metadata}` - 用户元数据\n- `{ticket_metadata}` - 工单元数据\n- `{similar_tickets}` - 相似工单\n- `{ticket_history}` - 工单历史\n- `{additional_information}` - 附加信息\n- `{client_query}` - 客户端查询\n\n资料来源：[core/quivr_core/rag/prompts.py:1-50]()\n\n### 5. 流式响应生成\n\n`QuivrQARAG` 类实现了流式响应生成，通过 `answer_astream` 方法逐块返回 LLM 输出：\n\n```python\nasync def answer_astream(\n self,\n question: str,\n chat_history: ChatHistory,\n user_metadata: Dict[str, Any],\n # ... 其他参数\n) -> AsyncIterator[ParsedRAGChunkResponse]:\n```\n\n流式响应包含以下数据块结构：\n\n| 字段 | 类型 | 说明 |\n|-----|------|-----|\n| `answer` | str | 当前块的文本内容 |\n| `metadata` | dict | 关联的来源文档信息 |\n| `last_chunk` | bool | 是否为最后一个数据块 |\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:20-45]()\n\n## 完整处理流程图\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant RAG as QuivrQARAG\n participant VS as VectorStore\n participant LLM as LLMEndpoint\n participant KB as 知识库\n\n U->>RAG: 发送查询问题\n RAG->>RAG: filter_history() 过滤历史\n \n alt 使用 LangGraph 工作流\n RAG->>RAG: rewrite_question() 重写问题\n RAG->>RAG: select_files() 选择文件\n RAG->>RAG: run_retrieval() 执行检索\n end\n \n RAG->>VS: 相似度搜索\n VS->>KB: 查询向量索引\n KB-->>VS: 返回相关文档\n VS-->>RAG: SearchResult 列表\n \n RAG->>RAG: compress_documents() 文档压缩\n RAG->>RAG: 构建提示词\n \n RAG->>LLM: 发送提示词\n LLM-->>RAG: 流式文本块\n \n loop 每个文本块\n RAG-->>U: ParsedRAGChunkResponse\n end\n \n RAG-->>U: 最终元数据块 (last_chunk=True)\n```\n\n## 文档处理管道\n\n在文档被摄入系统时，处理器会执行以下转换步骤：\n\n1. **文件解析** - 通过处理器提取文本内容\n2. **语言检测** - 使用 `detect_language` 函数识别文档语言\n3. **分块处理** - 将长文档分割为可管理的块\n4. **元数据增强** - 添加 chunk_index、quivr_core_version 等信息\n5. **UTF-8 规范化** - 处理特殊字符和编码问题\n\n```python\ndoc.metadata = {\n \"chunk_index\": idx,\n \"quivr_core_version\": qvr_version,\n \"language\": detect_language(\n text=doc.page_content.replace(\"\\\\n\", \" \").replace(\"\\n\", \" \"),\n low_memory=True,\n ).value,\n **file.metadata,\n **doc.metadata,\n **self.processor_metadata,\n}\n```\n\n资料来源：[core/quivr_core/processor/processor_base.py:1-30]()\n\n## 检索配置加载\n\n支持从 YAML 配置文件加载检索配置：\n\n```python\nretrieval_config = RetrievalConfig.from_yaml(config_file_name)\n```\n\n配置示例：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"llm\"]\n temperature: 0.7\n```\n\n资料来源：[README.md:30-60]()\n\n## 使用示例\n\n### 基础 RAG 问答\n\n```python\nfrom quivr_core import Brain\n\nbrain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[\"./document.pdf\"],\n)\n\nanswer = brain.ask(\"文档的主要内容是什么？\")\nprint(answer.answer)\n```\n\n### 自定义检索配置\n\n```python\nfrom quivr_core.config import RetrievalConfig\n\nconfig = RetrievalConfig.from_yaml(\"./basic_rag_workflow.yaml\")\nanswer = brain.ask(\n \"问题内容\",\n retrieval_config=config\n)\n```\n\n## 总结\n\nQuivr 的 RAG 处理流程通过模块化设计实现了高效的检索增强生成能力。核心流程包括聊天历史过滤、向量检索、文档重排序、提示词构建和大语言模型生成，最终通过流式接口返回响应结果。该架构支持灵活的配置和扩展，能够适应不同的应用场景需求。\n\n---\n\n\n\n## Brain 核心概念\n\n### 相关页面\n\n相关主题：[存储系统](#page-storage), [文件处理系统](#page-processor)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n- [core/quivr_core/storage/local_storage.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/local_storage.py)\n- [examples/simple_question/simple_question.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question/simple_question.py)\n- [examples/save_load_brain.py](https://github.com/QuivrHQ/quivr/blob/main/examples/save_load_brain.py)\n- [examples/pdf_parsing_tika.py](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py)\n
\n\n# Brain 核心概念\n\n## 概述\n\nBrain（大脑）是 Quivr 项目的核心抽象概念，它代表了一个基于生成式 AI 的个人知识库助手系统。Brain 将文档处理、向量存储检索和大语言模型问答有机结合，为用户提供与私有文档进行自然语言交互的能力。\n\nQuivr 的 Brain 采用 RAG（检索增强生成）架构，支持多种文件类型、多种 LLM 提供商，并允许用户通过 YAML 配置文件自定义检索策略和工作流程。\n\n## 核心组件\n\n### Brain 类\n\n`Brain` 类是整个系统的核心，位于 `core/quivr_core/brain/brain.py`。它封装了大脑的所有功能：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 大脑唯一标识符 |\n| `name` | str | 大脑名称 |\n| `storage` | BrainStorage | 文件存储后端 |\n| `llm` | LLMEndpoint | 大语言模型接口 |\n| `embedder` | Embeddings | 文档嵌入模型 |\n| `vector_db` | VectorDBInput | 向量数据库 |\n\n### 创建 Brain\n\n#### 从文件创建\n\n```python\nfrom quivr_core import Brain\n\nbrain = Brain.from_files(\n name=\"my_smart_brain\",\n file_paths=[\"./my_first_doc.pdf\", \"./my_second_doc.txt\"],\n)\n```\n\n#### 异步创建\n\n```python\nbrain = await Brain.afrom_files(\n name=\"test_brain\",\n file_paths=[temp_file.name]\n)\n```\n\n#### 从 LangChain 文档创建\n\n```python\nfrom langchain_core.documents import Document\nfrom quivr_core import Brain\n\ndocuments = [Document(page_content=\"Hello, world!\")]\nbrain = await Brain.afrom_langchain_documents(\n name=\"My Brain\",\n langchain_documents=documents\n)\n```\n\n## 核心功能\n\n### 问答功能 (ask)\n\nBrain 的主要功能是回答用户关于已加载文档的问题：\n\n```python\nanswer = brain.ask(\"what is gold? answer in french\")\nprint(\"answer:\", answer)\n```\n\n问答流程如下：\n\n```mermaid\ngraph TD\n A[用户问题] --> B[检索配置解析]\n B --> C{是否指定LLM}\n C -->|是| D[使用指定LLM]\n C -->|否| E[使用Brain默认LLM]\n D --> F[创建QuivrQARAGLangGraph]\n E --> F\n F --> G[向量数据库检索相关文档]\n G --> H[构建聊天历史]\n H --> I[调用LLM生成答案]\n I --> J[返回Answer对象]\n```\n\n### 异步流式问答 (ask_streaming)\n\n支持流式输出，适合实时展示生成过程：\n\n```python\nasync for chunk in brain.ask_streaming(\"What is the meaning of life?\"):\n print(chunk.answer)\n```\n\n### 文档检索 (asearch)\n\n直接检索向量数据库中的相关文档块：\n\n```python\nresults = await brain.asearch(\n query=\"查询文本\",\n n_results=5,\n fetch_n_neighbors=20\n)\n```\n\n## 数据模型\n\n### Answer 对象\n\n`ask()` 方法返回 `Answer` 对象，包含：\n\n- `answer`: 生成的答案文本\n- `sources`: 答案来源的文档块\n- `metadata`: 额外的元数据信息\n\n### SearchResult 对象\n\n`asearch()` 方法返回 `SearchResult` 列表，每个结果包含：\n\n- `content`: 文档内容\n- `metadata`: 文档元数据\n- `score`: 相关性分数\n\n## 配置管理\n\n### RetrievalConfig\n\n检索配置控制 RAG 工作流的行为：\n\n```python\nfrom quivr_core.config import RetrievalConfig\n\nretrieval_config = RetrievalConfig.from_yaml(config_file_name)\n\nanswer = brain.ask(\n question,\n retrieval_config=retrieval_config\n)\n```\n\n### YAML 工作流配置\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"retrieval\"]\n```\n\n## 持久化与加载\n\n### 保存 Brain\n\n```python\nsave_path = await brain.save(\"/home/user/.local/quivr\")\n```\n\n保存机制使用 SHA-1 哈希检测重复文件，避免存储冗余：\n\n```python\n# 资料来源：core/quivr_core/storage/local_storage.py:45-52\nif file.file_sha1 in self.hashes and not exists_ok:\n raise FileExistsError(f\"file {file.original_filename} already uploaded\")\n```\n\n### 加载 Brain\n\n```python\nbrain_loaded = Brain.load(save_path)\nbrain_loaded.print_info()\n```\n\n## 高级配置\n\n### 自定义 LLM\n\n```python\nfrom quivr_core.rag.entities.config import LLMEndpointConfig\nfrom quivr_core.llm.llm_endpoint import LLMEndpoint\nfrom langchain_core.language_models import FakeListChatModel\n\nbrain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[\"tests/processor/data/dummy.pdf\"],\n llm=LLMEndpoint(\n llm=FakeListChatModel(responses=[\"good\"]),\n llm_config=LLMEndpointConfig(model=\"fake_model\", llm_base_url=\"local\"),\n ),\n embedder=DeterministicFakeEmbedding(size=20),\n)\n```\n\n### 自定义解析器\n\n```python\nprocessor_kwargs = {\n \"megaparse_config\": megaparse_config,\n \"splitter_config\": assistant_config.ingestion_config.parser_config.splitter_config,\n}\n\nbrain = await Brain.afrom_files(\n name=\"test_brain\",\n file_paths=file_path,\n processor_kwargs=processor_kwargs,\n)\n```\n\n## 支持的文件类型\n\nQuivr Brain 支持处理多种文件类型：\n\n- PDF 文档\n- TXT 文本文件\n- Markdown 文件\n- 支持自定义解析器扩展\n\n## 信息查看\n\n查看 Brain 的详细信息：\n\n```python\nbrain.print_info()\n```\n\n## 系统架构图\n\n```mermaid\ngraph TB\n subgraph \"用户层\"\n A[用户提问]\n B[流式输出]\n end\n \n subgraph \"Brain 核心\"\n C[Brain.ask]\n D[RetrievalConfig]\n E[QuivrQARAGLangGraph]\n F[RAG 工作流]\n end\n \n subgraph \"检索层\"\n G[向量数据库]\n H[嵌入模型]\n I[元数据过滤]\n end\n \n subgraph \"生成层\"\n J[LLM Endpoint]\n K[聊天历史]\n L[系统提示词]\n end\n \n A --> C\n C --> D\n D --> E\n E --> F\n F --> G\n F --> H\n F --> I\n F --> J\n J --> B\n```\n\n## 最佳实践\n\n1. **选择合适的嵌入模型**：嵌入模型直接影响检索质量\n2. **配置检索参数**：根据文档复杂度调整 `n_results` 和 `fetch_n_neighbors`\n3. **使用 YAML 配置**：通过配置文件管理复杂的工作流，便于调整和版本控制\n4. **异步处理大文件**：使用 `afrom_files()` 和 `ask_streaming()` 提升性能\n\n---\n\n\n\n## 文件处理系统\n\n### 相关页面\n\n相关主题：[Brain 核心概念](#page-brain), [存储系统](#page-storage)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/processor/processor_base.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/processor_base.py)\n- [core/quivr_core/processor/registry.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/registry.py)\n- [core/quivr_core/processor/splitter.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/splitter.py)\n- [core/quivr_core/processor/implementations/default.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/implementations/default.py)\n- [core/quivr_core/processor/implementations/megaparse_processor.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/implementations/megaparse_processor.py)\n- [core/quivr_core/processor/implementations/tika_processor.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/implementations/tika_processor.py)\n- [examples/pdf_parsing_tika.py](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py)\n- [examples/simple_question_megaparse.py](https://github.com/QuivrHQ/quivr/blob/main/examples/simple_question_megaparse.py)\n
\n\n# 文件处理系统\n\n## 概述\n\nQuivr 的文件处理系统是构建检索增强生成（RAG）工作流的核心组件，负责将各种格式的文档转换为可供大语言模型（LLM）处理的文本块（chunks）。该系统采用插件化架构，通过处理器注册表动态加载和支持多种文件类型，支持包括 PDF、Word、文本、CSV、HTML、Markdown 等常见文档格式。\n\n系统的设计目标是将非结构化文档内容标准化为统一的 `Document` 对象格式，同时通过文本分割器将长文档切分为适合嵌入和检索的语义块。这一处理流程确保了后续的向量数据库索引和问答系统能够高效准确地工作。\n\n## 核心架构\n\n### 系统组件\n\n```mermaid\ngraph TD\n A[QuivrFile] --> B[ProcessorRegistry]\n B --> C[ProcessorBase]\n C --> D[process_file]\n D --> E[process_file_inner]\n E --> F[ProcessedDocument]\n F --> G[Document Chunks]\n G --> H[向量数据库]\n I[Language Detection] --> F\n J[Metadata Enrichment] --> F\n```\n\n### 处理流程\n\n文件处理的核心流程包含以下步骤：\n\n1. **文件验证**：检查文件扩展名是否在支持列表中\n2. **内容提取**：调用具体处理器的 `process_file_inner` 方法提取文本\n3. **语言检测**：使用 `detect_language` 函数自动识别文档语言\n4. **元数据丰富**：添加处理版本、块索引、语言标识等元数据\n5. **文本分割**：按配置的 `SplitterConfig` 将文档分割为块\n6. **格式标准化**：处理 Unicode 特殊字符和编码问题\n\n## ProcessorBase 基类\n\n### 类定义与接口\n\n`ProcessorBase` 是所有文件处理器的抽象基类，定义在 `processor_base.py` 中：\n\n```python\nclass ProcessorBase(ABC, Generic[R]):\n supported_extensions: list[FileExtension | str]\n \n @property\n @abstractmethod\n def processor_metadata(self) -> dict[str, Any]:\n raise NotImplementedError\n \n async def process_file(self, file: QuivrFile) -> ProcessedDocument[R]:\n # 处理逻辑\n```\n\n### ProcessedDocument 数据结构\n\n处理器返回的 `ProcessedDocument` 包含三个核心字段：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `chunks` | `List[Document]` | 分割后的文档块列表 |\n| `processor_cls` | `str` | 处理器类名标识 |\n| `processor_response` | `R` | 处理器特定响应数据 |\n\n### 元数据处理逻辑\n\n处理过程中会自动丰富每个文档块的元数据：\n\n```python\ndoc.metadata = {\n \"chunk_index\": idx, # 块在文档中的位置\n \"quivr_core_version\": qvr_version, # 版本信息\n \"language\": detect_language(...).value, # 检测到的语言\n **file.metadata, # 文件原始元数据\n **doc.metadata, # 文档自身元数据\n **self.processor_metadata, # 处理器特定元数据\n}\n```\n\n资料来源：[processor_base.py:30-50](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/processor_base.py)\n\n## 处理器注册表\n\n### 注册机制\n\n`registry.py` 实现了动态处理器加载机制，支持按优先级回退：\n\n```python\ndef fetch_processor_class(file_extension: FileExtension) -> Type[ProcessorBase]:\n if file_extension not in registry:\n entries = known_processors[file_extension]\n while entries:\n proc_entry = heappop(entries)\n try:\n register_processor(file_extension, _import_class(proc_entry.cls_mod))\n break\n except ImportError:\n logger.warn(f\"{proc_entry.err}. Falling to next...\")\n```\n\n### 优先级回退策略\n\n当某个处理器因缺少依赖无法加载时，系统自动尝试下一个候选处理器：\n\n| 优先级 | 处理器类型 | 依赖要求 |\n|--------|------------|----------|\n| 高 | MegaparseProcessor | megaparse 包 |\n| 中 | TikaProcessor | Apache Tika |\n| 低 | DefaultProcessor | langchain 加载器 |\n\n资料来源：[registry.py:30-55](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/registry.py)\n\n## 文本分割器配置\n\n### SplitterConfig 配置项\n\n分割器通过 `SplitterConfig` 数据类配置：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `chunk_size` | `int` | 500 | 每个块的字符数 |\n| `chunk_overlap` | `int` | 0 | 块之间的重叠字符数 |\n| `splitter_name` | `str` | \"RecursiveCharacter\" | 分割器类型 |\n\n资料来源：[splitter.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/splitter.py)\n\n### 分割器实现\n\nQuivr 使用 LangChain 的 `RecursiveCharacterTextSplitter` 作为默认分割器，该分割器按优先级尝试按不同分隔符分割文本，确保语义完整性。\n\n## 处理器实现\n\n### DefaultProcessor\n\n默认处理器基于 LangChain 社区的文档加载器构建，支持多种格式：\n\n| 文件类型 | LangChain 加载器 |\n|----------|------------------|\n| PDF | `UnstructuredPDFLoader` |\n| Word | `Docx2txtLoader` |\n| CSV | `CSVLoader` |\n| HTML | `UnstructuredHTMLLoader` |\n| Markdown | `UnstructuredMarkdownLoader` |\n| Excel | `UnstructuredExcelLoader` |\n| PowerPoint | `UnstructuredPowerPointLoader` |\n\n处理器类通过动态工厂模式构建，每个类包含支持的扩展名列表和对应的分割器配置。\n\n资料来源：[implementations/default.py:15-35](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/implementations/default.py)\n\n### TikaProcessor\n\nTika 处理器基于 Apache Tika 引擎，提供更强大的 PDF 解析能力：\n\n```python\nclass TikaProcessor(ProcessorBase):\n supported_extensions = [FileExtension.pdf]\n```\n\nTika 能够提取 PDF 的文本内容、元数据并处理复杂的文档结构。\n\n### MegaparseProcessor\n\nMegaparse 处理器是 Quivr 官方开发的高性能解析器，针对大规模文档处理优化：\n\n```python\nclass MegaparseProcessor(ProcessorBase):\n supported_extensions = [FileExtension.pdf, FileExtension.txt]\n \n @property\n def processor_metadata(self) -> dict[str, Any]:\n return {\n \"processor_cls\": \"MegaparseProcessor\",\n \"parser\": \"megaparse\",\n }\n```\n\n## 使用示例\n\n### 基本用法\n\n使用 `Brain.from_files` 方法时，系统自动选择合适的处理器：\n\n```python\nfrom quivr_core import Brain\n\nbrain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[\"./document.pdf\", \"./notes.txt\"],\n)\nanswer = brain.ask(\"What is the main topic?\")\n```\n\n### 指定 Tika 处理器解析 PDF\n\n```python\nfrom langchain_core.embeddings import DeterministicFakeEmbedding\nfrom langchain_core.language_models import FakeListChatModel\nfrom quivr_core import Brain\nfrom quivr_core.rag.entities.config import LLMEndpointConfig\nfrom quivr_core.llm.llm_endpoint import LLMEndpoint\nfrom quivr_core.processor.implementations.tika_processor import TikaProcessor\n\nbrain = Brain.from_files(\n name=\"pdf_brain\",\n file_paths=[\"document.pdf\"],\n processor=TikaProcessor(),\n llm=LLMEndpoint(\n llm=FakeListChatModel(responses=[\"good\"]),\n llm_config=LLMEndpointConfig(model=\"fake_model\", llm_base_url=\"local\"),\n ),\n embedder=DeterministicFakeEmbedding(size=20),\n)\n```\n\n资料来源：[examples/pdf_parsing_tika.py](https://github.com/QuivrHQ/quivr/blob/main/examples/pdf_parsing_tika.py)\n\n### 指定 Megaparse 处理器\n\n```python\nfrom quivr_core import Brain\nfrom quivr_core.processor.implementations megaparse_processor import MegaparseProcessor\n\nbrain = Brain.from_files(\n name=\"megaparse_brain\",\n file_paths=[\"document.pdf\"],\n processor=MegaparseProcessor(),\n)\n```\n\n## 扩展自定义处理器\n\n### 实现步骤\n\n1. 继承 `ProcessorBase` 基类\n2. 定义 `supported_extensions` 列表\n3. 实现 `process_file_inner` 异步方法\n4. 实现 `processor_metadata` 属性\n\n### 示例代码\n\n```python\nfrom quivr_core.processor.processor_base import ProcessedDocument, ProcessorBase\nfrom quivr_core.files.file import QuivrFile\nfrom langchain_core.documents import Document\n\nclass CustomProcessor(ProcessorBase):\n supported_extensions = [\".custom\"]\n \n @property\n def processor_metadata(self) -> dict[str, Any]:\n return {\"processor_cls\": \"CustomProcessor\"}\n \n async def process_file_inner(self, file: QuivrFile) -> ProcessedDocument[str]:\n # 实现自定义解析逻辑\n content = await self.extract_content(file)\n return ProcessedDocument(\n chunks=[Document(page_content=content, metadata={})],\n processor_cls=\"CustomProcessor\",\n processor_response=content,\n )\n```\n\n## 错误处理\n\n### 常见错误类型\n\n| 错误类型 | 原因 | 处理方式 |\n|----------|------|----------|\n| `ValueError` | 不支持的文件扩展名 | 检查 `supported_extensions` |\n| `ImportError` | 缺少处理器依赖 | 安装相应依赖或使用回退处理器 |\n\n### 验证机制\n\n处理器在执行前会验证文件类型：\n\n```python\ndef check_supported(self, file: QuivrFile) -> None:\n if file.file_extension not in self.supported_extensions:\n raise ValueError(f\"can't process a file of type {file.file_extension}\")\n```\n\n资料来源：[processor_base.py:35-38](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/processor/processor_base.py)\n\n## 总结\n\nQuivr 的文件处理系统通过模块化设计和动态加载机制，提供了灵活且可扩展的文档处理能力。处理器注册表配合优先级回退策略确保了系统的鲁棒性，而统一的 `ProcessedDocument` 接口使得不同处理器的输出可以被后续组件无缝使用。开发者可以通过实现 `ProcessorBase` 接口轻松添加新的文件格式支持。\n\n---\n\n\n\n## 存储系统\n\n### 相关页面\n\n相关主题：[Brain 核心概念](#page-brain), [文件处理系统](#page-processor)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/storage/storage_base.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/storage_base.py)\n- [core/quivr_core/storage/local_storage.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/local_storage.py)\n- [core/quivr_core/storage/file.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/storage/file.py)\n- [examples/custom_storage.md](https://github.com/QuivrHQ/quivr/blob/main/examples/custom_storage.md)\n
\n\n# 存储系统\n\n## 概述\n\nQuivr 的存储系统是整个 RAG（检索增强生成）框架的核心组件之一，负责管理文件的存取、元数据管理以及文件到向量数据库的转换流程。存储系统采用了抽象基类设计模式，支持本地存储和透明存储两种实现方式，同时允许开发者通过实现 `StorageBase` 接口来创建自定义存储后端。\n\n存储系统的主要职责包括：\n\n- 文件的读取与写入操作\n- 文件元数据的提取与管理（包括文件大小、SHA1 哈希值、文件扩展名等）\n- 支持异步文件操作以提高性能\n- 为处理器提供统一的文件访问接口\n\n资料来源：[core/quivr_core/brain/brain.py](core/quivr_core/brain/brain.py)\n\n## 核心架构\n\n### 存储系统类层次结构\n\n```mermaid\ngraph TD\n A[StorageBase] --> B[LocalStorage]\n A --> C[TransparentStorage]\n A --> D[Custom Storage]\n \n E[QuivrFile] --> F[文件元数据]\n G[process_files] --> A\n H[Brain] --> G\n```\n\n### 核心组件\n\n| 组件 | 类型 | 职责 |\n|------|------|------|\n| `StorageBase` | 抽象基类 | 定义存储系统接口规范 |\n| `LocalStorage` | 具体实现 | 本地文件系统存储 |\n| `TransparentStorage` | 具体实现 | 透明存储包装器 |\n| `QuivrFile` | 数据类 | 文件元数据与路径管理 |\n\n资料来源：[core/quivr_core/storage/storage_base.py](core/quivr_core/storage/storage_base.py)\n\n## StorageBase 抽象基类\n\n`StorageBase` 是所有存储实现的基类，定义了存储系统的核心接口规范。\n\n### 主要接口方法\n\n| 方法名 | 返回类型 | 说明 |\n|--------|----------|------|\n| `get_files()` | `AsyncGenerator[QuivrFile]` | 异步获取存储中的所有文件 |\n| `add_file()` | `None` | 添加文件到存储 |\n| `get_file_by_id()` | `QuivrFile` | 根据 ID 获取文件 |\n\n### 抽象方法定义\n\n```python\nclass StorageBase(ABC):\n @abstractmethod\n async def get_files(self) -> AsyncGenerator[QuivrFile, None]:\n raise NotImplementedError\n \n @abstractmethod\n async def add_file(self, file: QuivrFile) -> None:\n raise NotImplementedError\n```\n\n资料来源：[core/quivr_core/storage/storage_base.py](core/quivr_core/storage/storage_base.py)\n\n## QuivrFile 文件元数据类\n\n`QuivrFile` 是用于表示存储中文件的数据类，使用 `__slots__` 优化内存占用。\n\n### 数据结构\n\n```python\nclass QuivrFile:\n __slots__ = [\n \"id\", # UUID 文件唯一标识\n \"brain_id\", # UUID 所属脑部ID\n \"path\", # Path 文件路径\n \"original_filename\", # str 原始文件名\n \"file_size\", # int 文件大小\n \"file_extension\", # FileExtension 文件扩展名\n \"file_sha1\", # str SHA1哈希值\n \"additional_metadata\", # dict 额外元数据\n ]\n```\n\n### 构造函数参数\n\n| 参数名 | 类型 | 必需 | 说明 |\n|--------|------|------|------|\n| `id` | `UUID` | 是 | 文件唯一标识符 |\n| `original_filename` | `str` | 是 | 文件原始名称 |\n| `path` | `Path` | 是 | 文件存储路径 |\n| `file_sha1` | `str` | 是 | 文件 SHA1 哈希值 |\n| `file_extension` | `FileExtension \\| str` | 是 | 文件扩展名 |\n| `brain_id` | `UUID \\| None` | 否 | 关联的脑部 ID |\n| `file_size` | `int \\| None` | 否 | 文件大小（字节） |\n| `metadata` | `dict \\| None` | 否 | 额外元数据字典 |\n\n资料来源：[core/quivr_core/files/file.py](core/quivr_core/files/file.py)\n\n### 异步文件打开\n\n`QuivrFile` 提供了异步上下文管理器用于安全地打开文件：\n\n```python\n@asynccontextmanager\nasync def open(self) -> AsyncGenerator[AsyncIterable[bytes], None]:\n f = await aiofiles.open(self.path, mode=\"rb\")\n try:\n yield f\n finally:\n await f.close()\n```\n\n资料来源：[core/quivr_core/files/file.py](core/quivr_core/files/file.py)\n\n## LocalStorage 本地存储实现\n\n`LocalStorage` 是基于本地文件系统的存储实现，适用于单节点部署场景。\n\n### 文件处理流程\n\n```mermaid\ngraph TD\n A[开始处理] --> B{文件是否存在}\n B -->|不存在| C[抛出 ValueError]\n B -->|存在| D[提取文件扩展名]\n D --> E[计算 SHA1 哈希]\n E --> F[计算文件大小]\n F --> G[创建 QuivrFile 对象]\n G --> H[添加到文件列表]\n H --> I[返回 QuivrFile]\n```\n\n### 核心功能\n\n| 功能 | 说明 |\n|------|------|\n| 批量文件加载 | 从指定目录加载所有支持的文件 |\n| 元数据自动提取 | 自动计算文件哈希和大小 |\n| 文件扩展名识别 | 识别并返回文件类型 |\n\n资料来源：[core/quivr_core/storage/local_storage.py](core/quivr_core/storage/local_storage.py)\n\n## TransparentStorage 透明存储\n\n`TransparentStorage` 是一个存储包装器，用于在不改变现有接口的情况下扩展存储功能。\n\n### 使用场景\n\n- 日志记录：透明地记录所有存储操作\n- 缓存层：在存储操作前后添加缓存逻辑\n- 访问控制：添加权限检查逻辑\n\n资料来源：[core/quivr_core/rag/quivr_rag_langgraph.py](core/quivr_core/rag/quivr_rag_langgraph.py)\n\n## 文件处理集成\n\n存储系统与处理器系统紧密集成，形成完整的文件处理流水线：\n\n```mermaid\ngraph LR\n A[StorageBase] -->|get_files| B[process_files]\n B -->|QuivrFile| C[get_processor_class]\n C -->|ProcessorBase| D[process_file]\n D -->|Document| E[向量数据库]\n```\n\n### 异步处理流程\n\n```python\nasync def process_files(\n storage: StorageBase, \n skip_file_error: bool, \n **processor_kwargs: dict[str, Any]\n) -> list[Document]:\n```\n\n处理流程说明：\n\n1. 遍历存储中的所有文件\n2. 根据文件扩展名获取对应的处理器\n3. 调用处理器提取文档内容\n4. 返回 LangChain Document 列表\n\n资料来源：[core/quivr_core/brain/brain.py](core/quivr_core/brain/brain.py)\n\n## 自定义存储实现\n\n开发者可以通过继承 `StorageBase` 来实现自定义存储后端。\n\n### 实现步骤\n\n1. 创建继承自 `StorageBase` 的新类\n2. 实现 `get_files()` 异步生成器方法\n3. 实现 `add_file()` 异步方法\n4. 在 Brain 初始化时传入自定义存储实例\n\n### 示例结构\n\n```python\nclass CustomStorage(StorageBase):\n async def get_files(self) -> AsyncGenerator[QuivrFile, None]:\n # 实现自定义文件获取逻辑\n ...\n \n async def add_file(self, file: QuivrFile) -> None:\n # 实现自定义文件添加逻辑\n ...\n```\n\n资料来源：[examples/custom_storage.md](https://github.com/QuivrHQ/quivr/blob/main/examples/custom_storage.md)\n\n## 配置与使用\n\n### 在 Brain 中使用存储\n\n```python\nfrom quivr_core import Brain\nfrom quivr_core.storage.local_storage import LocalStorage\n\n# 使用默认本地存储\nbrain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[\"./documents/\"]\n)\n\n# 使用自定义存储\nbrain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[],\n storage=CustomStorage(...)\n)\n```\n\n资料来源：[README.md](README.md)\n\n## 最佳实践\n\n### 性能优化\n\n| 实践 | 说明 |\n|------|------|\n| 异步操作 | 所有文件 I/O 操作均使用异步方式 |\n| 内存效率 | 使用 `__slots__` 减少对象内存占用 |\n| 错误处理 | 支持 `skip_file_error` 参数跳过无法处理的文件 |\n\n### 错误处理\n\n存储系统在处理文件时会进行多种校验：\n\n- 文件扩展名识别\n- 文件 SHA1 哈希计算\n- 文件大小统计\n- 路径有效性验证\n\n资料来源：[core/quivr_core/files/file.py](core/quivr_core/files/file.py)\n\n## 总结\n\nQuivr 的存储系统采用模块化设计，通过抽象基类 `StorageBase` 提供了灵活的可扩展性。开发者可以根据实际需求选择本地存储、透明存储或实现自定义存储后端。存储系统与处理器系统的紧密集成使得文件到向量数据库的转换过程透明且高效。\n\n---\n\n\n\n## LLM 集成\n\n### 相关页面\n\n相关主题：[RAG 处理流程](#page-rag-flow), [工具扩展系统](#page-tools)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/quivr_core/llm/llm_endpoint.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/llm/llm_endpoint.py)\n- [core/quivr_core/rag/entities/config.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/config.py)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/rag/quivr_rag_langgraph.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag_langgraph.py)\n- [core/quivr_core/rag/entities/models.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/models.py)\n- [core/quivr_core/rag/prompts.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/prompts.py)\n
\n\n# LLM 集成\n\nQuivr 的 LLM 集成模块是整个 RAG（检索增强生成）系统的核心组件，负责与大语言模型交互以生成智能回答。本模块提供了灵活的 LLM 端点配置、支持多种模型提供商，并深度集成了 LangChain 生态系统。\n\n## 架构概述\n\nQuivr 的 LLM 集成采用分层架构设计，通过 `LLMEndpoint` 类封装底层模型调用，提供统一的接口供 RAG 工作流使用。\n\n```mermaid\ngraph TD\n subgraph \"LLM 集成层\"\n A[LLMEndpoint] --> B[LLMEndpointConfig]\n A --> C[BaseChatModel]\n end\n \n subgraph \"RAG 工作流\"\n D[QuivrRAG] --> A\n E[QuivrRAGLangGraph] --> A\n end\n \n subgraph \"模型提供商\"\n F[OpenAI] --> A\n G[Anthropic] --> A\n H[Mistral] --> A\n I[Ollama 本地模型] --> A\n end\n```\n\n## 核心组件\n\n### LLMEndpoint\n\n`LLMEndpoint` 是 LLM 集成的核心类，位于 `core/quivr_core/llm/llm_endpoint.py`。它封装了 LangChain 的聊天模型，提供配置管理和调用接口。\n\n```python\nfrom quivr_core.llm.llm_endpoint import LLMEndpoint\nfrom quivr_core.rag.entities.config import LLMEndpointConfig\n\nllm = LLMEndpoint(\n llm=chat_model_instance,\n llm_config=LLMEndpointConfig(\n model=\"gpt-4\",\n temperature=0.7,\n max_tokens=2000\n )\n)\n```\n\n### LLMEndpointConfig 配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `model` | `str` | 必需 | 模型标识符，如 \"gpt-4\"、\"claude-3\" |\n| `temperature` | `float` | `0.7` | 生成温度，控制随机性 |\n| `max_tokens` | `int` | `2000` | 最大生成 token 数 |\n| `llm_base_url` | `str` | `None` | API 基础 URL（用于代理或自定义端点） |\n| `streaming` | `bool` | `True` | 是否启用流式输出 |\n\n资料来源：[core/quivr_core/rag/entities/config.py:1-100]()\n\n## 配置管理\n\n### 默认 LLM 配置\n\nQuivr 提供了默认 LLM 工厂函数，简化常见场景下的配置：\n\n```python\nfrom quivr_core.llm import default_llm\n\n# 使用默认配置创建 LLM\nllm = default_llm()\n```\n\n### 环境变量配置\n\nLLM 集成支持通过环境变量配置 API 密钥：\n\n```python\nimport os\nos.environ[\"OPENAI_API_KEY\"] = \"your-api-key\"\nos.environ[\"ANTHROPIC_API_KEY\"] = \"your-anthropic-key\"\nos.environ[\"MISTRAL_API_KEY\"] = \"your-mistral-key\"\n```\n\n## 模型支持\n\nQuivr 的 LLM 集成支持多种模型提供商：\n\n### 支持的提供商\n\n| 提供商 | 模型示例 | 配置方式 |\n|--------|----------|----------|\n| OpenAI | GPT-4, GPT-3.5-turbo | `OPENAI_API_KEY` |\n| Anthropic | Claude-3 Opus, Claude-3 Sonnet | `ANTHROPIC_API_KEY` |\n| Mistral | Mistral Large, Mistral Medium | `MISTRAL_API_KEY` |\n| Ollama | 本地部署的开源模型 | 本地 URL 配置 |\n\n### 本地模型支持（Ollama）\n\nQuivr 支持使用 Ollama 运行本地大语言模型：\n\n```python\nfrom langchain_ollama import ChatOllama\n\nllm = ChatOllama(\n model=\"llama2\",\n base_url=\"http://localhost:11434\"\n)\n\nconfig = LLMEndpointConfig(\n model=\"llama2\",\n llm_base_url=\"http://localhost:11434\"\n)\n\nendpoint = LLMEndpoint(llm=llm, llm_config=config)\n```\n\n## RAG 中的 LLM 集成\n\n### QuivrRAG 类\n\n`QuivrRAG` 类是核心 RAG 实现，通过 LLMEndpoint 进行问答生成：\n\n```mermaid\nsequenceDiagram\n User->>QuivrRAG: ask(question)\n QuivrRAG->>VectorDB: search(query, n_results)\n VectorDB-->>QuivrRAG: relevant_chunks\n QuivrRAG->>LLMEndpoint: generate(prompt)\n LLMEndpoint->>LLM: chat.completions.create\n LLM-->>LLMEndpoint: response\n LLMEndpoint-->>QuivrRAG: ParsedRAGChunkResponse\n QuivrRAG-->>User: RAGResponse\n```\n\n### 流式响应处理\n\nLLM 集成支持流式输出，通过 `answer_astream` 方法实现：\n\n```python\nasync for chunk in brain.asearch_stream(question):\n print(chunk.answer, end=\"\", flush=True)\n```\n\n流式响应的关键流程：\n\n1. 逐块接收 LLM 返回的响应\n2. 实时解析并格式化输出\n3. 最后一块包含完整的元数据\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:100-200]()\n\n## 工作流节点配置\n\nLLM 集成可配置在工作流节点中，通过 YAML 文件定义：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"retrieval\"]\n```\n\n### RetrievalConfig 配置\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `max_tokens` | `int` | 单次响应最大 token 数 |\n| `temperature` | `float` | 生成温度 |\n| `n_results` | `int` | 检索返回的结果数量 |\n\n资料来源：[core/quivr_core/rag/entities/config.py]()\n\n## 提示词模板\n\nQuivr 的 LLM 集成使用结构化的提示词模板系统：\n\n### 模板类型\n\n| 模板名称 | 用途 |\n|----------|------|\n| `CONDENSE_QUESTION` | 问题改写模板 |\n| `DEFAULT_ANSWER` | 默认回答模板 |\n| `HISTORY_AUGMENT` | 历史增强模板 |\n\n### 自定义提示词\n\n可以通过 `custom_prompts` 配置自定义提示词：\n\n```python\nfrom quivr_core.rag.prompts import custom_prompts, TemplatePromptName\n\ncustom_prompts[TemplatePromptName.DEFAULT_ANSWER] = {\n \"prompt\": \"自定义提示词模板...\",\n \"guidelines\": \"自定义指南...\"\n}\n```\n\n资料来源：[core/quivr_core/rag/prompts.py]()\n\n## LangChain 集成\n\nQuivr 的 LLM 集成深度集成 LangChain 生态系统：\n\n### LangChain 兼容性\n\n```python\nfrom langchain_core.language_models import FakeListChatModel\nfrom langchain_core.embeddings import DeterministicFakeEmbedding\nfrom quivr_core import Brain\n\n# 使用 Fake LLM 进行测试\nbrain = Brain.from_files(\n name=\"test_brain\",\n file_paths=[\"./docs.pdf\"],\n llm=LLMEndpoint(\n llm=FakeListChatModel(responses=[\"测试回答\"]),\n llm_config=LLMEndpointConfig(model=\"fake_model\", llm_base_url=\"local\")\n ),\n embedder=DeterministicFakeEmbedding(size=20)\n)\n```\n\n### Langfuse 追踪集成\n\nLLM 调用支持 Langfuse 追踪，便于性能监控和调试：\n\n```python\nfrom quivr_core.rag.utils import LangfuseService\n\nlangfuse_service = LangfuseService()\nlangfuse_handler = langfuse_service.get_handler()\n```\n\n资料来源：[core/quivr_core/rag/quivr_rag_langgraph.py]()\n\n## 高级配置\n\n### 模型参数覆盖\n\n在 `Brain.ask()` 调用时可以覆盖默认配置：\n\n```python\nanswer = brain.ask(\n question,\n retrieval_config=RetrievalConfig(\n max_tokens=1000,\n temperature=0.5\n )\n)\n```\n\n### 多模型路由\n\nQuivr 支持在工作流中配置多模型路由：\n\n```python\n# 为不同节点指定不同模型\nconfig = RetrievalConfig(\n model_configs={\n \"rewrite\": {\"model\": \"gpt-3.5-turbo\", \"temperature\": 0.3},\n \"answer\": {\"model\": \"gpt-4\", \"temperature\": 0.7}\n }\n)\n```\n\n## 错误处理\n\nLLM 集成内置了完整的错误处理机制：\n\n| 错误类型 | 处理方式 |\n|----------|----------|\n| `APIError` | 重试机制，最多 3 次 |\n| `RateLimitError` | 指数退避等待 |\n| `AuthenticationError` | 抛出明确的认证错误 |\n| `TimeoutError` | 10 秒超时限制 |\n\n## 最佳实践\n\n### 1. 生产环境配置\n\n```python\nconfig = LLMEndpointConfig(\n model=\"gpt-4-turbo\",\n temperature=0.3, # 降低随机性\n max_tokens=2000,\n streaming=True\n)\n```\n\n### 2. 成本优化\n\n- 使用 `gpt-3.5-turbo` 处理简单查询\n- 启用流式输出减少感知延迟\n- 合理设置 `max_tokens` 避免浪费\n\n### 3. 安全性\n\n- 使用环境变量存储 API 密钥\n- 避免在日志中记录敏感信息\n- 实施请求频率限制\n\n## 总结\n\nQuivr 的 LLM 集成模块提供了灵活、高效的大语言模型集成方案。通过统一的 `LLMEndpoint` 接口，开发者可以轻松切换不同的模型提供商，同时保持 RAG 工作流的稳定性。深度集成的 LangChain 支持和完善的配置管理使 Quivr 成为构建智能问答系统的理想选择。\n\n---\n\n\n\n## 工具扩展系统\n\n### 相关页面\n\n相关主题：[LLM 集成](#page-llm), [工作流配置](#page-workflow)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [core/README.md](https://github.com/QuivrHQ/quivr/blob/main/core/README.md)\n- [README.md](https://github.com/QuivrHQ/quivr/blob/main/README.md)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/brain/brain.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/brain/brain.py)\n
\n\n# 工具扩展系统\n\n## 概述\n\nQuivr 的工具扩展系统是实现 RAG（检索增强生成）工作流自定义的核心组件，允许用户为 LLM（大语言模型）集成额外的工具能力，如网络搜索、API 调用等。根据项目文档，Quivr 支持\"添加工具\"（add tools）功能，使用户能够扩展基础 RAG 的能力范围。\n\n资料来源：[README.md:1-50]()\n\n## 架构设计\n\n### 工具系统与 RAG 的关系\n\n工具扩展系统与 `QuivrQARAG` 类紧密集成。根据源码设计，`QuivrQARAG` 接受 `RetrievalConfig` 配置，并支持在检索过程中注入重排序（reranker）等扩展组件。这种模块化设计使得工具系统可以无缝嵌入 RAG 工作流。\n\n```mermaid\ngraph TD\n A[用户查询] --> B[QuivrQARAG]\n B --> C{检索配置}\n C --> D[向量存储检索]\n C --> E[历史过滤]\n C --> F[查询改写]\n D --> G[工具扩展层]\n G --> H[LLM 端点]\n H --> I[生成回答]\n \n F -->|可选| J[网络搜索工具]\n G -->|可扩展| K[自定义工具]\n```\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:50-80]()\n\n### 核心组件结构\n\n根据项目架构设计，工具扩展系统涉及以下核心组件：\n\n| 组件 | 作用 | 位置 |\n|------|------|------|\n| LLMEndpoint | LLM 调用端点封装 | core/quivr_core/llm/ |\n| RetrievalConfig | 检索配置管理 | core/quivr_core/rag/entities/config.py |\n| QuivrQARAG | RAG 核心引擎 | core/quivr_core/rag/quivr_rag.py |\n| Brain | 大脑抽象层 | core/quivr_core/brain/brain.py |\n\n资料来源：[core/quivr_core/brain/brain.py:1-100]()\n\n## 配置与使用\n\n### 基础配置流程\n\n用户可以通过 YAML 配置文件定义工具扩展的工作流程：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n - name: \"rewrite\"\n edges: [\"END\"]\n```\n\n资料来源：[README.md:1-100]()\n\n### LLM 端点配置\n\n工具系统支持多种 LLM 提供商，包括：\n\n- **OpenAI**：通过 `OPENAI_API_KEY` 环境变量配置\n- **Anthropic**：支持 Claude 系列模型\n- **Mistral**：支持 Mistral AI 模型\n- **Ollama**：支持本地模型部署\n\n```python\nfrom quivr_core.config import RetrievalConfig\n\nconfig_file_name = \"./basic_rag_workflow.yaml\"\nretrieval_config = RetrievalConfig.from_yaml(config_file_name)\n```\n\n资料来源：[README.md:1-80]()\n\n## 工作流程集成\n\n### 问答流程\n\n工具扩展系统在 `Brain.ask()` 方法中被调用，完整流程如下：\n\n1. **历史过滤**（filter_history）：过滤相关聊天历史\n2. **查询改写**（rewrite）：优化用户查询\n3. **检索**（retrieve）：从向量数据库获取相关内容\n4. **工具执行**（可选）：如网络搜索等扩展工具\n5. **生成回答**：LLM 基于检索结果和工具输出生成答案\n\n```mermaid\ngraph LR\n A[用户提问] --> B[filter_history]\n B --> C[rewrite]\n C --> D{是否需要工具}\n D -->|是| E[执行工具]\n D -->|否| F[直接检索]\n E --> F\n F --> G[LLM 生成]\n G --> H[返回答案]\n```\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:100-150]()\n\n### 异步搜索接口\n\n`Brain` 类提供了异步搜索方法，支持灵活的工具扩展集成：\n\n```python\nasync def asearch(\n self,\n query: str | Document,\n n_results: int = 5,\n filter: Callable | Dict[str, Any] | None = None,\n fetch_n_neighbors: int = 20,\n) -> list[SearchResult]\n```\n\n资料来源：[core/quivr_core/brain/brain.py:100-120]()\n\n## 扩展机制\n\n### 自定义工具注册\n\n根据项目架构设计，工具系统支持用户注册自定义处理器和加载器：\n\n```python\nfrom quivr_core.processor.processor_base import ProcessorBase\nfrom quivr_core.files.file import FileExtension, QuivrFile\n\nclass CustomProcessor(ProcessorBase):\n supported_extensions = [\".custom\"]\n \n async def process_file_inner(self, file: QuivrFile) -> ProcessedDocument:\n # 自定义处理逻辑\n pass\n```\n\n资料来源：[core/quivr_core/processor/implementations/default.py:1-50]()\n\n### 支持的文件格式\n\n工具系统通过处理器基类支持多种文件格式：\n\n| 格式 | 处理器 | 状态 |\n|------|--------|------|\n| PDF | UnstructuredPDFLoader | 支持 |\n| TXT | TextLoader | 支持 |\n| Markdown | UnstructuredMarkdownLoader | 支持 |\n| DOCX | Docx2txtLoader | 支持 |\n| CSV | CSVLoader | 支持 |\n| Excel | UnstructuredExcelLoader | 支持 |\n| HTML | UnstructuredHTMLLoader | 支持 |\n\n资料来源：[core/quivr_core/processor/implementations/default.py:10-30]()\n\n## 版本与兼容性\n\n工具扩展系统随 `quivr-core` 包发布，版本信息记录在文档元数据中：\n\n```python\nqvr_version = version(\"quivr-core\")\ndoc.metadata = {\n \"chunk_index\": idx,\n \"quivr_core_version\": qvr_version,\n \"language\": detect_language(text=...).value,\n **file.metadata,\n **doc.metadata,\n **self.processor_metadata,\n}\n```\n\n资料来源：[core/quivr_core/processor/processor_base.py:20-40]()\n\n## 快速开始\n\n### 完整示例\n\n```python\nimport tempfile\nfrom quivr_core import Brain\nfrom quivr_core.config import RetrievalConfig\n\n# 创建 Brain\nbrain = Brain.from_files(\n name=\"my_brain\",\n file_paths=[\"./documents/\"],\n)\n\n# 配置检索（含工具扩展）\nretrieval_config = RetrievalConfig.from_yaml(\"./config.yaml\")\n\n# 提问\nanswer = brain.ask(\n \"您的技术问题\",\n retrieval_config=retrieval_config\n)\n\nprint(answer.answer)\n```\n\n资料来源：[README.md:40-70]()\n\n## 总结\n\nQuivr 的工具扩展系统通过模块化设计，将 LLM 工具能力与 RAG 工作流深度整合。系统支持自定义工具注册、多 LLM 提供商集成，以及灵活的工作流配置，为构建智能问答应用提供了强大的扩展基础。开发者可以通过继承 `ProcessorBase` 类或配置 YAML 工作流文件来扩展系统能力。\n\n---\n\n\n\n## 工作流配置\n\n### 相关页面\n\n相关主题：[RAG 处理流程](#page-rag-flow)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [examples/chatbot/basic_rag_workflow.yaml](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot/basic_rag_workflow.yaml)\n- [examples/chatbot_voice/basic_rag_workflow.yaml](https://github.com/QuivrHQ/quivr/blob/main/examples/chatbot_voice/basic_rag_workflow.yaml)\n- [core/example_workflows/talk_to_file_rag_config_workflow.yaml](https://github.com/QuivrHQ/quivr/blob/main/core/example_workflows/talk_to_file_rag_config_workflow.yaml)\n- [core/quivr_core/rag/entities/config.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/entities/config.py)\n- [core/quivr_core/rag/quivr_rag.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag.py)\n- [core/quivr_core/rag/quivr_rag_langgraph.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/quivr_rag_langgraph.py)\n- [core/quivr_core/rag/prompts.py](https://github.com/QuivrHQ/quivr/blob/main/core/quivr_core/rag/prompts.py)\n
\n\n# 工作流配置\n\n## 概述\n\n工作流配置（Workflow Configuration）是 Quivr Core 框架中用于定义 RAG（检索增强生成）流程的核心机制。通过 YAML 格式的配置文件，用户可以灵活地定义检索、生成和对话历史处理的各个环节，实现高度定制化的问答系统。\n\n工作流配置的主要作用包括：\n\n- **定义处理流程节点**：指定 RAG 流程中的各个处理阶段（如历史过滤、问题改写、文档检索、答案生成）\n- **配置节点间连接**：通过边（edges）定义节点之间的执行顺序和数据流向\n- **控制对话历史**：设置历史消息的过滤策略和最大上下文长度\n- **配置重排序器**：选择重排序模型以提升检索结果质量\n- **调整 LLM 参数**：控制生成答案的最大输入令牌数和温度参数\n\n## 配置结构\n\n工作流配置文件采用 YAML 格式，整体结构如下：\n\n```yaml\nworkflow_config:\n name: \"工作流名称\"\n nodes:\n - name: \"节点名称\"\n edges: [\"下一节点名称\"]\n\nmax_history: 10\n\nreranker_config:\n supplier: \"cohere\"\n model: \"rerank-multilingual-v3.0\"\n top_n: 5\n\nllm_config:\n max_input_tokens: 4000\n temperature: 0.7\n```\n\n## 核心配置项\n\n### workflow_config（工作流配置）\n\n定义 RAG 处理流程的节点拓扑结构。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 工作流名称，用于标识和日志记录 |\n| nodes | list | 是 | 节点列表，每个节点定义一个处理阶段 |\n\n**节点定义**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 节点唯一标识名称 |\n| edges | list | 是 | 该节点的出边列表，指定下一个执行的节点 |\n\n节点名称必须是预定义的系统节点，当前支持的节点包括：\n\n- `START`：流程起始节点\n- `filter_history`：对话历史过滤节点\n- `rewrite`：问题改写节点\n- `retrieve`：文档检索节点\n- `generate_rag`：RAG 答案生成节点（通常是最后一个节点）\n- `END`：流程结束节点\n\n资料来源：[examples/chatbot/basic_rag_workflow.yaml:1-22]()\n\n### max_history（历史消息配置）\n\n控制对话历史中包含的最大迭代次数。\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| max_history | int | 10 | 包含在答案上下文中的历史对话轮次数量 |\n\n此参数用于限制传入 LLM 的历史消息数量，防止上下文过长导致令牌浪费和性能下降。\n\n### reranker_config（重排序配置）\n\n配置文档重排序器以提升检索结果的相关性。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| supplier | string | 是 | 重排序服务提供商（如 `cohere`） |\n| model | string | 是 | 具体使用的重排序模型名称 |\n| top_n | int | 是 | 重排序后返回的文档块数量 |\n\n当前支持的重排序供应商包括 `cohere`，模型推荐使用 `rerank-multilingual-v3.0`。\n\n资料来源：[examples/chatbot/basic_rag_workflow.yaml:24-32]()\n\n### llm_config（语言模型配置）\n\n配置用于答案生成的大语言模型参数。\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| max_input_tokens | int | 是 | 传递给 LLM 的最大输入令牌数 |\n| temperature | float | 是 | LLM 生成答案的温度参数（0-1之间） |\n\n- `temperature` 越低，答案越确定性；越高，答案越有创造性\n- `max_input_tokens` 应根据 LLM 的上下文窗口和文档数量合理设置\n\n## 工作流执行流程\n\n### 标准 RAG 流程图\n\n```mermaid\ngraph TD\n START([START]) --> FILTER[filter_history]\n FILTER --> REWRITE[rewrite]\n REWRITE --> RETRIEVE[retrieve]\n RETRIEVE --> GENERATE[generate_rag]\n GENERATE --> END([END])\n \n style START fill:#90EE90\n style END fill:#FFB6C1\n```\n\n### 各节点功能详解\n\n#### filter_history（历史过滤）\n\n该节点负责过滤和精简对话历史，只保留最近 N 轮对话内容。配置参数为 `max_history`，用于控制保留的历史对话对数。\n\n资料来源：[core/quivr_core/rag/quivr_rag.py:120-140]()\n\n#### rewrite（问题改写）\n\n将用户当前问题与对话历史结合，改写为独立的、上下文无关的问题，以便更好地进行文档检索。这一步确保即使问题依赖历史上下文，也能准确检索相关文档。\n\n#### retrieve（文档检索）\n\n基于改写后的问题，从向量数据库中检索最相关的文档块。检索结果的数量由 `reranker_config.top_n` 控制。\n\n#### generate_rag（答案生成）\n\n将检索到的文档块与问题、历史上下文结合，调用 LLM 生成最终答案。最终节点的输出会流式返回给用户。\n\n## 配置类定义\n\n工作流配置在代码中由以下数据类定义：\n\n```python\nclass RetrievalConfig(BaseModel):\n max_history: int = 10\n prompt: Optional[str] = None\n reranker_config: Optional[RerankerConfig] = None\n llm_config: Optional[LLMConfig] = None\n```\n\n资料来源：[core/quivr_core/rag/entities/config.py]()\n\n### RerankerConfig（重排序配置类）\n\n```python\nclass RerankerConfig(BaseModel):\n supplier: str\n model: str\n top_n: int\n```\n\n### LLMConfig（语言模型配置类）\n\n```python\nclass LLMConfig(BaseModel):\n max_input_tokens: int\n temperature: float\n```\n\n### NodeConfig（节点配置类）\n\n```python\nclass NodeConfig(BaseModel):\n name: str\n edges: List[str]\n```\n\n## 使用示例\n\n### 基本 RAG 工作流配置\n\n创建文件 `basic_rag_workflow.yaml`：\n\n```yaml\nworkflow_config:\n name: \"standard RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n\n - name: \"rewrite\"\n edges: [\"retrieve\"]\n\n - name: \"retrieve\"\n edges: [\"generate_rag\"]\n\n - name: \"generate_rag\"\n edges: [\"END\"]\n\nmax_history: 10\n\nreranker_config:\n supplier: \"cohere\"\n model: \"rerank-multilingual-v3.0\"\n top_n: 5\n\nllm_config:\n max_input_tokens: 4000\n temperature: 0.7\n```\n\n资料来源：[examples/chatbot/basic_rag_workflow.yaml:1-32]()\n\n### 在代码中使用配置\n\n```python\nfrom quivr_core import Brain\nfrom quivr_core.config import RetrievalConfig\n\nconfig_file_name = \"./basic_rag_workflow.yaml\"\nretrieval_config = RetrievalConfig.from_yaml(config_file_name)\n\nbrain = Brain.from_files(\n name=\"my_smart_brain\",\n file_paths=[\"./my_first_doc.pdf\", \"./my_second_doc.txt\"],\n)\n\nanswer = brain.ask(\n \"what is gold?\",\n retrieval_config=retrieval_config\n)\n```\n\n### 语音聊天工作流配置\n\n语音聊天场景的工作流配置与基本 RAG 类似，主要区别在于支持音频输入和语音合成：\n\n```yaml\nworkflow_config:\n name: \"voice RAG\"\n nodes:\n - name: \"START\"\n edges: [\"filter_history\"]\n\n - name: \"filter_history\"\n edges: [\"rewrite\"]\n\n - name: \"rewrite\"\n edges: [\"retrieve\"]\n\n - name: \"retrieve\"\n edges: [\"generate_rag\"]\n\n - name: \"generate_rag\"\n edges: [\"END\"]\n\nmax_history: 10\n\nreranker_config:\n supplier: \"cohere\"\n model: \"rerank-multilingual-v3.0\"\n top_n: 5\n\nllm_config:\n max_input_tokens: 4000\n temperature: 0.7\n```\n\n资料来源：[examples/chatbot_voice/basic_rag_workflow.yaml:1-32]()\n\n## 高级配置：自定义提示词\n\n除了系统默认的提示词模板外，用户可以通过 `llm_config.prompt` 参数添加自定义指令：\n\n```yaml\nllm_config:\n max_input_tokens: 4000\n temperature: 0.7\n prompt: |\n 请用简洁的语言回答，并在答案开头用一句话总结。\n```\n\n自定义提示词会与系统默认指令合并，系统会在生成答案时综合考虑两者的要求。\n\n## LangGraph 高级工作流\n\nQuivr 还支持基于 LangGraph 的高级工作流，通过 `quivr_rag_langgraph.py` 模块实现：\n\n```python\nfrom quivr_core.rag.quivr_rag_langgraph import QuivrRAGLangGraph\n\nrag = QuivrRAGLangGraph(\n retrieval_config=retrieval_config,\n brain=brain,\n)\n```\n\nLangGraph 工作流支持更复杂的条件分支和状态管理，适合需要多步骤推理的应用场景。\n\n资料来源：[core/quivr_core/rag/quivr_rag_langgraph.py]()\n\n## 最佳实践\n\n### 1. 合理设置 max_history\n\n- **低值（1-3）**：适用于简单问答场景，减少上下文长度\n- **中值（5-10）**：适用于需要多轮对话的应用\n- **高值（15+）**：适用于长对话分析，但会增加令牌消耗\n\n### 2. 优化 top_n 参数\n\n- **文档简短**：可设置较高值（10-20）\n- **文档冗长**：建议设置较低值（3-5），减少上下文干扰\n\n### 3. 调整 temperature\n\n- **事实性问答**：建议 0.1-0.3\n- **创意性生成**：建议 0.7-0.9\n- **平衡场景**：建议 0.5 左右\n\n### 4. 配置加载方式\n\n支持从 YAML 文件或 Python 代码直接配置：\n\n```python\n# 从 YAML 加载\nconfig = RetrievalConfig.from_yaml(\"config.yaml\")\n\n# 直接创建\nconfig = RetrievalConfig(\n max_history=5,\n reranker_config=RerankerConfig(\n supplier=\"cohere\",\n model=\"rerank-multilingual-v3.0\",\n top_n=5\n ),\n llm_config=LLMConfig(\n max_input_tokens=4000,\n temperature=0.7\n )\n)\n```\n\n## 相关文件\n\n| 文件路径 | 说明 |\n|----------|------|\n| `core/quivr_core/rag/entities/config.py` | 配置数据类定义 |\n| `core/quivr_core/rag/quivr_rag.py` | 标准 RAG 工作流实现 |\n| `core/quivr_core/rag/quivr_rag_langgraph.py` | LangGraph 工作流实现 |\n| `core/quivr_core/rag/prompts.py` | 提示词模板定义 |\n| `examples/chatbot/basic_rag_workflow.yaml` | 聊天机器人示例配置 |\n| `examples/chatbot_voice/basic_rag_workflow.yaml` | 语音聊天示例配置 |\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：QuivrHQ/quivr\n\n摘要：发现 17 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：EU AI Act Compliance Scan Results — Sharing Findings for Feedback。\n\n## 1. 安全/权限坑 · 来源证据：EU AI Act Compliance Scan Results — Sharing Findings for Feedback\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：EU AI Act Compliance Scan Results — Sharing Findings for Feedback\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_46118108af95480ba852109be6e2c66a | https://github.com/QuivrHQ/quivr/issues/3667 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：[Bug]:\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]:\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff260ca3ab5247679b2ded201ec21e24 | https://github.com/QuivrHQ/quivr/issues/2004 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Integration idea: Screenpipe for screen/audio context\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Integration idea: Screenpipe for screen/audio context\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3a7f345691d04bbea72b03858746645e | https://github.com/QuivrHQ/quivr/issues/3658 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e3091b23b6184dffb982e0cc494134fd | https://github.com/QuivrHQ/quivr/issues/3650 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 能力判断依赖假设\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:640079149 | https://github.com/QuivrHQ/quivr | README/documentation is current enough for a first validation pass.\n\n## 6. 运行坑 · 来源证据：The garbage collector is trying to clean up non-checked-in connection >, which will…\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6fdde799a2b4f53806121190979025a | https://github.com/QuivrHQ/quivr/issues/3654 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 运行坑 · 来源证据：core: v0.0.25\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.25\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7c6096fb5a6442c7b53068a8dd8e2c78 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.25 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 运行坑 · 来源证据：core: v0.0.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.29\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7eeeeb626a10476e820fcd651727a55a | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.29 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 运行坑 · 来源证据：core: v0.0.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.33\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7a735cb41bc44f2abeb148d689f1320 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.33 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 来源证据：core: v0.0.24\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：core: v0.0.24\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5272fe70cda24220a5aeb994ad06819e | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.24 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · 来源证据：core: v0.0.26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：core: v0.0.26\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7f723b616fd446c3be43298d75fd6e8b | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.26 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:640079149 | https://github.com/QuivrHQ/quivr | last_activity_observed missing\n\n## 13. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:640079149 | https://github.com/QuivrHQ/quivr | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:640079149 | https://github.com/QuivrHQ/quivr | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：core: v0.0.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：core: v0.0.27\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_027338ba02764da6b371970615591265 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.27 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 维护坑 · 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:640079149 | https://github.com/QuivrHQ/quivr | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:640079149 | https://github.com/QuivrHQ/quivr | 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项目：QuivrHQ/quivr\n\n摘要：发现 17 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：EU AI Act Compliance Scan Results — Sharing Findings for Feedback。\n\n## 1. 安全/权限坑 · 来源证据：EU AI Act Compliance Scan Results — Sharing Findings for Feedback\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：EU AI Act Compliance Scan Results — Sharing Findings for Feedback\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_46118108af95480ba852109be6e2c66a | https://github.com/QuivrHQ/quivr/issues/3667 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：[Bug]:\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]:\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ff260ca3ab5247679b2ded201ec21e24 | https://github.com/QuivrHQ/quivr/issues/2004 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Integration idea: Screenpipe for screen/audio context\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Integration idea: Screenpipe for screen/audio context\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3a7f345691d04bbea72b03858746645e | https://github.com/QuivrHQ/quivr/issues/3658 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: RuntimeError: There is no current event loop in thread 'MainThread' when using Brain.from_files() in script\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e3091b23b6184dffb982e0cc494134fd | https://github.com/QuivrHQ/quivr/issues/3650 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 能力坑 · 能力判断依赖假设\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:640079149 | https://github.com/QuivrHQ/quivr | README/documentation is current enough for a first validation pass.\n\n## 6. 运行坑 · 来源证据：The garbage collector is trying to clean up non-checked-in connection >, which will…\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e6fdde799a2b4f53806121190979025a | https://github.com/QuivrHQ/quivr/issues/3654 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 运行坑 · 来源证据：core: v0.0.25\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.25\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7c6096fb5a6442c7b53068a8dd8e2c78 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.25 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 8. 运行坑 · 来源证据：core: v0.0.29\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.29\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7eeeeb626a10476e820fcd651727a55a | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.29 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 9. 运行坑 · 来源证据：core: v0.0.33\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：core: v0.0.33\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_d7a735cb41bc44f2abeb148d689f1320 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.33 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 来源证据：core: v0.0.24\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：core: v0.0.24\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5272fe70cda24220a5aeb994ad06819e | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.24 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 11. 维护坑 · 来源证据：core: v0.0.26\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：core: v0.0.26\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7f723b616fd446c3be43298d75fd6e8b | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.26 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 12. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:640079149 | https://github.com/QuivrHQ/quivr | last_activity_observed missing\n\n## 13. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:640079149 | https://github.com/QuivrHQ/quivr | no_demo; severity=medium\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:640079149 | https://github.com/QuivrHQ/quivr | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：core: v0.0.27\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：core: v0.0.27\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_027338ba02764da6b371970615591265 | https://github.com/QuivrHQ/quivr/releases/tag/core-0.0.27 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 16. 维护坑 · 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:640079149 | https://github.com/QuivrHQ/quivr | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:640079149 | https://github.com/QuivrHQ/quivr | release_recency=unknown\n", "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。", "title": "Pitfall Log / 踩坑日志" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# quivr - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 quivr 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想快速理解一组资料，并得到结构化摘要、对比和继续研究的问题。\n我常用的宿主 AI：chatgpt\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Opiniated RAG for integrating GenAI in your apps 🧠 Focus on your product rather than the RAG. Easy integration in existing products with customisation! Any LLM: GPT4, Groq, Llama. Any Vectorstore: PGVector, Faiss. Any Files. Anyway you want. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-overview：项目概述。围绕“项目概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速入门指南。围绕“快速入门指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-rag-flow：RAG 处理流程。围绕“RAG 处理流程”模拟一次用户任务，不展示安装或运行结果。\n5. page-brain：Brain 核心概念。围绕“Brain 核心概念”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-overview\n输入：用户提供的“项目概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速入门指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-rag-flow\n输入：用户提供的“RAG 处理流程”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-brain\n输入：用户提供的“Brain 核心概念”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-overview：Step 1 必须围绕“项目概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速入门指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-architecture：Step 3 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-rag-flow：Step 4 必须围绕“RAG 处理流程”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-brain：Step 5 必须围绕“Brain 核心概念”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/QuivrHQ/quivr\n- https://github.com/QuivrHQ/quivr#readme\n- README.md\n- core/README.md\n- core/quivr_core/__init__.py\n- examples/simple_question/simple_question.py\n- examples/simple_question/simple_question_streaming.py\n- examples/chatbot/main.py\n- core/quivr_core/brain/brain.py\n- core/quivr_core/rag/quivr_rag.py\n- core/quivr_core/rag/quivr_rag_langgraph.py\n- core/quivr_core/config.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 quivr 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start / 官方入口\n\n项目：QuivrHQ/quivr\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install quivr-core\n```\n\n来源：https://github.com/QuivrHQ/quivr#readme\n\n## 来源\n\n- repo: https://github.com/QuivrHQ/quivr\n- docs: https://github.com/QuivrHQ/quivr#readme\n", "summary": "从项目官方 README 或安装文档提取的开工入口。", "title": "Quick Start / 官方入口" } }, "validation_id": "dval_cb34a15d24d14dc3a30e63e5b51ebb41" }