thaihai-swe/multi-source-qa-engine

# 🤖 多源问答引擎 [](https://www.python.org/downloads/) [](LICENSE) [](https://github.com) ## 📖 目录 - [概述](#overview) - [核心功能](#key-features) - [架构](#architecture) - [快速开始](#quick-start) - [安装说明](#installation) - [使用方法](#usage) - [CLI 命令](#cli-commands) - [配置](#configuration) - [系统能力](#system-capabilities) - [查询模式](#query-modes) - [评估与指标](#evaluation--metrics) - [安全与护栏](#safety--guardrails) - [文档](#documentation) - [项目结构](#project-structure) - [贡献指南](#contributing) ## 🎯 概述 **多源问答引擎** 是一个结合了以下特性的高级问答系统： - ⚡ **混合检索**（语义 + 关键词）以实现最佳检索效果 - 🧠 **多种推理模式**（simple, expand, multi-hop, agentic） - 📊 **综合评估**（RAGAS 指标、事实核查、幻觉检测） - 🛡️ **安全护栏**（PII 检测、偏见检测、毒性过滤） - 🔍 **Cross-Encoder 重排序**以提升精度 - 🎯 **MMR 多样性**以获取全面的答案 - 📚 **多源加载**（Wikipedia、URL、PDF、文本文件） **生产状态：** 95% 完成 - 所有核心功能均可正常运行的全功能系统 ## ✨ 核心功能 ### 🔍 高级检索 - **混合检索引擎**，结合语义（70%）和关键词（30%）并进行加权融合 - **Cross-Encoder 重排序**，改进相关性评分 - **MMR（最大边际相关性）**，实现结果多样化（λ=0.7） - **两阶段检索**（先广泛初搜，再精确重排） - **自适应分块**，通过父子层级结构提供最佳上下文 - **域守卫**，用于域外查询检测（阈值：0.35） - **段落高亮**，精确定位相关句子及其得分 ### 🧠 智能推理 - **4 种查询模式：** - `SIMPLE` - 直接检索并回答 - `EXPAND` - 查询扩展，生成 4 种语义变体 - `MULTIHOP` - 多跳推理，采用分解-检索-合成流程 - `AGENT` - 智能路由器，通过启发式规则选择最佳策略 - **意图分类**（混合模式：启发式 + 基于 LLM） - **自动模式选择**，基于查询复杂度和意图 - **自查询分解**，处理复杂的多方面查询 ### 📊 综合评估 - **RAGAS 框架**，包含 3 个核心指标： - 上下文相关性 - 答案相关性 - 忠实度 - **事实核查**，带有来源归属 - **幻觉检测**，提供详细报告 - **置信度评分**，评估答案可靠性 - **偏见检测**，用于公平性评估 ### 🛡️ 安全与防护 - **输入护栏：** - Prompt 注入检测 - PII（个人身份信息）脱敏 - 长度验证 - **输出护栏：** - 毒性过滤 - 偏见检测 - 有害内容预防 - **统一安全评估器**，提供风险评分 ### 🎨 生产级特性 - **LRU 缓存**，用于 Embedding（重复查询速度提升 50%） - **优雅降级**，在服务失败时维持运行 - **可观测性与监控**，提供详细指标 - **查询日志**，记录到 JSONL 以便审计追踪 - **动态温度控制**，根据查询类型调整 - **Token 追踪**，用于成本管理 ## 🏗️ 架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ Multi-Source QA Engine │ └─────────────────────────────────────────────────────────────┘ ┌────────────────┐ │ DATA SOURCES │ │ • Wikipedia │ │ • URLs │ │ • PDFs │ │ • Text Files │ └─────┬──────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ 11-STEP QUERY PIPELINE │ ├─────────────────────────────────────────────────────────────┤ │ 1. Input Validation (Guardrails) │ │ 2. Intent Classification (Heuristic + LLM) │ │ 3. Self-Query Decomposition │ │ 4. Domain Safety Check │ │ 5. Execute Strategy (SIMPLE/EXPAND/MULTIHOP/AGENT) │ │ 6. Rerank & Diversify (Cross-Encoder + MMR) │ │ 7. Generate Answer (LLM with Dynamic Temperature) │ │ 8. Evaluate & Fact-Check (RAGAS + Fact Checker) │ │ 9. Output Validation & Safety (Guardrails) │ │ 10. Token Counting & Cost Tracking │ │ 11. Query Logging & Persistence │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ RAG RESPONSE │ │ • Answer with confidence score │ │ • Retrieved documents with citations │ │ • RAGAS metrics │ │ • Fact-check results │ │ • Safety assessment │ │ • Token usage & cost │ └─────────────────────────────────────────────────────────────┘ ``` ### 模块组织（12 个模块） ``` src/ ├── models/ # Data models (9 dataclasses, fully typed) ├── core/ # Query pipeline, RAG system, strategies ├── retrieval/ # 3 strategies + advanced features ├── generation/ # LLM-based answer generation ├── evaluation/ # RAGAS, fact-checking, hallucination detection ├── safety/ # Input/output guardrails, bias detection ├── reasoning/ # Intent, mode selection, query decomposition ├── prompts/ # LLM prompt templates ├── utils/ # Logger, validators ├── persistence/ # Query logging to JSONL ├── cli/ # Interactive CLI interface └── config/ # Configuration with 45+ parameters ``` ## 🚀 快速开始 ### 前置条件 - Python 3.8+ - OpenAI 兼容 API 端点（OpenAI、LM Studio、Ollama 等） ### 安装说明 ``` # 克隆仓库 git clone https://github.com/yourusername/multi-source-qa-engine.git cd multi-source-qa-engine # 运行 setup 脚本（创建 venv 并安装依赖） ./setup.sh # 或者手动： python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate pip install -r requirements.txt ``` ### 环境设置 在项目根目录下创建一个 `.env` 文件： ``` # 必需 OPEN_AI_API_KEY=your-api-key-here # 可选（显示默认值） OPEN_AI_API_BASE_URL=http://localhost:1234/v1 OPEN_AI_MODEL=llama-3.1-8b RAG_DATA_DIR=./json_data RAG_DB_PATH=./chroma_db ``` ### 运行系统 ``` # 启动交互式 CLI ./run.sh # 或者直接 python main.py ``` ### 首次查询示例 ``` ❓ > load wikipedia "Artificial Intelligence" ✅ Loaded 1 Wikipedia articles: Artificial Intelligence ❓ > query "What is machine learning?" 🤔 Processing query in SIMPLE mode... 📄 Answer: Machine learning is a subset of artificial intelligence that enables systems to learn and improve from experience without being explicitly programmed... 📊 Confidence: 0.92 | RAGAS Score: 0.88 ✅ No hallucinations detected ``` ## 💻 使用方法 ### 基本查询 ``` ❓ > query "What is the capital of France?" ``` ### 加载不同来源 ``` # 加载 Wikipedia 文章 ❓ > load wikipedia "Machine Learning" # 从 URL 加载 ❓ > load url https://example.com/article # 加载 PDF 文件 ❓ > load file ./documents/paper.pdf # 加载文本文件 ❓ > load file ./documents/notes.txt ``` ### 高级查询模式 ``` # Query expansion（生成 4 个变体） ❓ > expand "climate change effects" # Multi-hop reasoning（用于复杂问题） ❓ > multihop "Who was the president when World War II ended and what policies did they implement?" # Agentic mode（自主策略选择） ❓ > agent "Compare the economic policies of..." ``` ### 查看指标与分析 ``` # 显示 RAGAS metrics ❓ > metrics # 显示 fact-check 结果 ❓ > facts # 显示高亮 passages ❓ > passages # 显示 hallucination report ❓ > hallucination-report # 显示 bias detection report ❓ > bias-report # 显示 domain statistics ❓ > domain-stats # 显示 cache statistics ❓ > cache # 显示 system status ❓ > status ``` ## 📋 CLI 命令 ### 核心命令 | 命令 | 描述 | | ---------------------------- | ---------------------------- | | `load [collection]` | 加载 Wikipedia、URL 或文件 | | `query ` | 标准 RAG 查询 | | `sources` | 显示已加载来源 | | `history` | 显示对话历史 | | `metrics` | 显示 RAGAS 指标 | | `save [filename]` | 保存对话 | | `clear` | 清除历史 | ### 高级命令 | 命令 | 描述 | | ------------------ | ------------------------------ | | `expand ` | 查询扩展（4 种变体） | | `multihop ` | 多跳推理 | | `agent ` | 使用 Agentic RAG | ### 分析与诊断 | 命令 | 描述 | | ------------------------- | ------------------------------ | | `cache` | 显示缓存统计 | | `analyze-chunks ` | 分析最佳分块大小 | | `facts` | 显示事实核查结果 | | `passages` | 显示高亮段落 | | `hallucination-report` | 显示上一次幻觉报告 | | `bias-report` | 显示偏见检测报告 | | `domain-stats` | 显示域守卫配置 | | `observability` | 显示可观测性指标 | | `experiments` | 运行优化实验 | ### 系统信息 | 命令 | 描述 | | ----------- | ------------------------------------ | | `status` | 显示活动功能与配置 | | `help` | 显示帮助 | | `quit/exit` | 退出系统 | ## ⚙️ 配置 系统通过 `src/config.py` 和环境变量进行配置。主要配置如下： ### LLM 配置 ``` LLMConfig: - api_key: From OPEN_AI_API_KEY env var - api_base_url: From OPEN_AI_API_BASE_URL env var (default: http://localhost:1234/v1) - model_name: From OPEN_AI_MODEL env var (default: llama-3.1-8b) - temperature: 0.4 (dynamically adjusted by mode/intent) - max_tokens: 1000 - use_dynamic_temperature: True ``` ### 搜索配置 ``` SearchConfig: - semantic_weight: 0.7 # Weight for semantic search - keyword_weight: 0.3 # Weight for keyword search - max_results: 5 - enable_domain_guard: True - use_cross_encoder: True - use_mmr_diversity: True - mmr_lambda: 0.7 # 70% relevance, 30% diversity - embedding_cache_size: 1000 ``` ### 推理配置 ``` ReasoningConfig: - auto_mode_selection: True - query_expansion_count: 4 - enable_multihop: True - max_reasoning_steps: 3 ``` ### 评估配置 ``` EvaluationConfig: - enable_ragas: True - enable_fact_checking: True - enable_hallucination_detection: True - min_confidence_threshold: 0.6 - bias_check_threshold: 0.7 ``` ### 安全配置 ``` SafetyConfig: - enable_input_validation: True - enable_output_validation: True - toxicity_threshold: 0.7 - enable_pii_masking: True ``` ## 🎯 系统能力 ### 检索策略 1. **语义搜索策略** - 使用 sentence-transformers bi-encoder 生成 Embedding - 在向量空间中进行余弦相似度匹配 - 最适合概念性和上下文相关的查询 - 混合模式中的权重：70% 2. **关键词搜索策略** - BM25（Okapi 变体）算法 - 最适合精确词语匹配和词汇精度 - 适用于姓名、日期、技术术语、特定短语 - 混合模式中的权重：30% 3. **混合搜索策略**（默认） - 结合语义（70%）+ 关键词（30%） - 归一化加权融合并进行去重 - 针对不同查询类型的最佳整体性能 ### 查询处理智能 - **自动模式选择**，基于查询复杂度 - **意图分类**（事实型、分析型、比较型、开放式等） - **动态温度控制**（0.3-0.8，基于意图） - **基于置信度的结果扩展**（动态 Top-K） - **域相关性过滤** ### 答案生成 - **基于 LLM 的生成**，附带来源引用 - **动态 Prompt**，基于意图和模式 - **温度优化**，平衡准确性与创造性 - **Token 管理**与成本追踪 - **优雅降级**，在生成失败时维持运行 ## 🔧 查询模式 ### 1. SIMPLE 模式 **最适合：** 简单直接的事实性问题 ``` ❓ > query "What is Python?" ``` **流程：** - 单次检索 - 直接生成答案 - 快速高效 ### 2. EXPAND 模式 **最适合：** 需要全面覆盖、探索多个方面的问题 ``` ❓ > expand "benefits of renewable energy" ``` **流程：** - 生成 4 种查询变体 - 针对每种变体检索 - 合并并去重结果 - 更全面但速度较慢 **扩展示例：** - “可再生能源有哪些好处？” - “可再生能源如何帮助环境？” - “可再生能源的经济优势是什么？” - “我们为什么要使用可再生能源？” ### 3. MULTIHOP 模式 **最适合：** 需要多步推理的复杂问题 ``` ❓ > multihop "Who founded the company that built the iPhone and what role did they have?" ``` **流程：** - 将查询分解为子问题 - 为每个子问题执行检索 - 跨步骤链接推理 - 综合最终答案 **分解示例：** 1. “哪家公司制造了 iPhone？” 2. “谁创立了那家公司？” 3. “他们担任什么角色？” ### 4. AGENT 模式 **最适合：** 让系统智能地路由到最佳策略 ``` ❓ > agent "Compare Python and JavaScript programming languages" ``` **流程：** - 分析查询模式和关键词 - 通过启发式规则路由到最佳策略： - “compare/difference/vs” → MULTIHOP - 长查询（>15 个词）→ EXPAND - 其他情况 → SIMPLE - 功能完备的智能路由器 - ⚠️ 注意：使用的是模式匹配，而非完整的强化学习 ReAct ## 📊 评估与指标 ### RAGAS 指标 系统使用 **RAGAS**（检索增强生成评估）框架： 1. **上下文相关性** (0.0-1.0) - 衡量检索到的文档与查询的相关程度 - 目标：> 0.7 2. **答案相关性** (0.0-1.0) - 衡量答案对问题的回答程度 - 目标：> 0.8 3. **忠实度** (0.0-1.0) - 衡量答案基于来源内容的程度 - 目标：> 0.85 **示例输出：** ``` 📊 RAGAS Metrics: Context Relevance: 0.88 ✅ Answer Relevance: 0.92 ✅ Faithfulness: 0.90 ✅ Overall Score: 0.90 ``` ### 事实核查 - 从生成的答案中提取主张 - 根据源文档验证每个主张 - 提供详细的验证状态 ``` ✅ Verified: "Machine learning is a subset of AI" ✅ Verified: "It enables systems to learn from data" ⚠️ Unverified: "It was invented in 1950" ``` ### 幻觉检测 - 检测不受支持的陈述 - 识别与来源的矛盾之处 - 报告置信水平 ``` 🔍 Hallucination Report: Total Claims: 5 Supported: 4 (80%) Unsupported: 1 (20%) Confidence: Medium ``` ## 🛡️ 安全与护栏 ### 输入护栏 1. **Prompt 注入检测** - 检测操纵系统行为的尝试 - 阻止恶意 Prompt 2. **PII 检测与脱敏** - 识别电子邮件、电话号码、SSN、信用卡 - 自动脱敏敏感信息 3. **长度验证** - 强制执行最小/最大查询长度 - 防止滥用 ### 输出护栏 1. **毒性过滤** - 检测有毒、仇恨或冒犯性内容 - 阻止不当响应 2. **偏见检测** - 检查性别、种族、政治偏见 - 提供偏见评估分数 3. **有害内容预防** - 过滤危险指令 - 确保响应安全 ### 安全评分 每个查询都会收到一个**风险评分**（0.0-1.0）： - **0.0-0.3：** 低风险 ✅ - **0.3-0.7：** 中风险 ⚠️ - **0.7-1.0：** 高风险 ❌ ## 📁 项目结构 ``` multi-source-qa-engine/ ├── main.py # Entry point ├── requirements.txt # Python dependencies ├── setup.sh # Setup script ├── run.sh # Run script ├── .env # Environment variables (create this) │ ├── src/ # Source code │ ├── models/ # Data models (9 dataclasses) │ │ ├── data_models.py # Core data structures │ │ └── enums.py # Enums (QueryMode, IntentType, etc.) │ │ │ ├── core/ # Core orchestration │ │ ├── rag_system.py # Main RAG orchestrator │ │ ├── query_pipeline.py # 11-step pipeline │ │ └── strategies.py # Strategy pattern implementation │ │ │ ├── retrieval/ # Retrieval components │ │ ├── strategies/ # Search strategies │ │ │ ├── semantic.py │ │ │ ├── keyword.py │ │ │ └── hybrid.py │ │ ├── hybrid_search.py # Hybrid search engine │ │ ├── reranker.py # Cross-encoder + MMR │ │ ├── chunker.py # Adaptive chunking │ │ ├── loader.py # Multi-source loading │ │ ├── domain_guard.py # Domain filtering │ │ └── passage_highlighter.py │ │ │ ├── generation/ # Answer generation │ │ ├── answer_generator.py │ │ └── llm_answer_generator.py │ │ │ ├── evaluation/ # Evaluation & metrics │ │ ├── ragas_evaluator.py │ │ ├── fact_checker.py │ │ ├── hallucination_detector.py │ │ └── observability.py │ │ │ ├── reasoning/ # Reasoning components │ │ ├── intent_classifier.py │ │ ├── mode_selector.py │ │ └── self_query_decomposer.py │ │ │ ├── safety/ # Safety & guardrails │ │ ├── guardrails.py # Input/output validation │ │ └── bias_detector.py # Bias detection │ │ │ ├── prompts/ # LLM prompts │ │ ├── generation.py # Answer generation prompts │ │ ├── retrieval.py # Retrieval prompts │ │ ├── reasoning.py # Reasoning prompts │ │ └── evaluation.py # Evaluation prompts │ │ │ ├── persistence/ # Data persistence │ │ └── __init__.py # JSON storage │ │ │ ├── utils/ # Utilities │ │ ├── logger.py # Logging │ │ └── validators.py # Validation │ │ │ ├── cli/ # CLI interface │ │ └── __init__.py # Interactive CLI │ │ │ └── config.py # Configuration │ ├── docs/ # Documentation │ └── AI_LEARNING_GUIDE.md # Complete learning guide │ ├── chroma_db/ # ChromaDB storage ├── json_data/ # Persisted data │ ├── query_logs.jsonl # Query logs │ └── temp_logs.json # Temporary logs │ └── .github/ └── copilot-instructions.md # GitHub Copilot config ``` ## 🔍 查询示例 ### 事实性问题 ``` ❓ > query "What is the speed of light?" ❓ > query "Who invented the telephone?" ❓ > query "When did World War II end?" ``` ### 分析性问题 ``` ❓ > expand "What are the causes of climate change?" ❓ > expand "How does photosynthesis work?" ``` ### 复杂多跳问题 ``` ❓ > multihop "Who directed the movie that won Best Picture in 2020 and what other films have they made?" ❓ > multihop "What is the capital of the country that borders France to the east?" ``` ### 比较分析 ``` ❓ > agent "Compare the advantages and disadvantages of solar vs wind energy" ❓ > agent "What are the differences between Python and JavaScript?" ``` ## 🚧 已知局限性 1. **Agent 模式** - 功能完备的启发式路由器，但非完整的基于 RL 的 ReAct（有待增强） 2. **性能** - 目前为同步 Pipeline，若使用异步执行有望实现 30-50% 的速度提升 3. **测试** - 单元测试覆盖率约 60%，缺少全面的集成测试 4. **错误处理** - 尚未在所有模块中完全标准化 5. **AgenticStrategy Bug** - 委托时缺少 config/client 的初始化（可能出现 AttributeError） ## 🛠️ 开发 ### 运行测试 ``` # 运行所有 tests pytest # 运行 with coverage pytest --cov=src # 运行特定 test file pytest tests/test_retrieval.py ``` ### 扩展系统 **添加新的检索策略：** . 在 `src/retrieval/strategies/` 中创建类 2. 继承 `SearchStrategy` 基类 3. 实现 `search()` 方法 4. 在策略工厂中注册 **添加新的评估指标：** 1. 在 `src/evaluation/` 中创建评估器 2. 实现评估逻辑 3. 集成到 `QueryPipeline` 中 ## 📈 性能基准 | 指标 | 值 | | -------------------------- | --------- | | 平均查询时间 (Simple) | ~2-3s | | 平均查询时间 (Expand) | ~8-10s | | 平均查询时间 (Multihop) | ~12-15s | | 缓存命中率 | ~40-50% | | 速度提升 (缓存后) | ~50% | | RAGAS 评分 (平均) | 0.85-0.90 | | 幻觉率 | <5% | ## 🤝 贡献指南 欢迎贡献代码！请遵循以下准则： 1. Fork 本仓库 2. 创建功能分支 3. 遵循代码风格进行更改 4. 为新功能编写测试 5. 提交 Pull Request **代码质量规则：** - 遵循 `.github/copilot-instructions.md` 中的重构指南 - 更新现有代码而不是创建重复代码 - 立即删除过时代码 - 确保所有新代码都集成到系统中 ## 📄 许可证 本项目采用 MIT 许可证授权 - 详情请参阅 LICENSE 文件。 ## 🙏 致谢 - **ChromaDB** - 向量数据库 - **Sentence-Transformers** - Embedding 模型 - **OpenAI** - LLM API - **RAGAS** - 评估框架 - **Rank-BM25** - 关键词搜索 - **NLTK** - 自然语言处理 ## 📞 支持 如有问题、疑问或功能请求： - 在 GitHub 上开启 Issue - 查看 [AI 学习指南](docs/AI_LEARNING_GUIDE.md) 获取详细解释 - 阅读 [架构文档](memories/repo/qa-engine-architecture.md) ## 🗺️ 路线图 ### 即将推出的功能 - [ ] 完善的 Agent 模式（ReAct 循环） - [ ] 异步/并行执行以提升性能 - [ ] 更多数据源（Google Drive、Notion 等） - [ ] Web UI 界面 - [ ] API 端点（REST/GraphQL） - [ ] 多语言支持 - [ ] 微调能力 - [ ] 高级缓存策略 - [ ] 分布式部署支持 **用 ❤️ 构建的生产级 AI 应用** *版本 4.0 | 最后更新：2026 年 2 月*

标签：AI问答系统, Clair, MMR, Petitpotam, PII检测, Python, RAG, RAGAS评估, 事实核查, 偏见检测, 关键词检索, 向量检索, 多源知识库, 多跳推理, 大语言模型应用, 安全护栏, 文本分块, 无后门, 机器学习工程, 检索增强生成, 毒性过滤, 混合搜索, 生产级, 语义搜索, 跨编码器重排序, 逆向工具, 问答引擎, 领域防护