{"id":32798217,"url":"https://github.com/vivy1024/daml-rag-framework","last_synced_at":"2026-04-11T12:45:12.838Z","repository":{"id":322665590,"uuid":"1090452123","full_name":"vivy1024/daml-rag-framework","owner":"vivy1024","description":"🧠 DAML-RAG: Domain-Adaptive Multi-source Learning RAG Framework | GraphRAG混合检索 + 推理时学习 + 教师-学生双模型协作 | Production-ready vertical domain AI solution","archived":false,"fork":false,"pushed_at":"2025-12-15T15:43:26.000Z","size":862,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T12:44:53.121Z","etag":null,"topics":["artificial-intelligence","framework","graphrag","in-context-learning","knowledge-graph","llm","machine-learning","mcp","neo4j","python","qdrant","rag","vector-database"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vivy1024.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-05T17:26:28.000Z","updated_at":"2025-12-17T14:45:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vivy1024/daml-rag-framework","commit_stats":null,"previous_names":["vivy1024/daml-rag-framework"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/vivy1024/daml-rag-framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivy1024%2Fdaml-rag-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivy1024%2Fdaml-rag-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivy1024%2Fdaml-rag-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivy1024%2Fdaml-rag-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vivy1024","download_url":"https://codeload.github.com/vivy1024/daml-rag-framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vivy1024%2Fdaml-rag-framework/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31681201,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T08:18:19.405Z","status":"ssl_error","status_checked_at":"2026-04-11T08:17:08.892Z","response_time":54,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["artificial-intelligence","framework","graphrag","in-context-learning","knowledge-graph","llm","machine-learning","mcp","neo4j","python","qdrant","rag","vector-database"],"created_at":"2025-11-06T00:04:09.611Z","updated_at":"2026-04-11T12:45:12.828Z","avatar_url":"https://github.com/vivy1024.png","language":"Python","readme":"# DAML-RAG框架 v2.0\n\n**Domain Adaptive Multi-source Learning RAG Framework**\n\n面向垂直领域的自适应多源学习型检索增强生成框架\n\n[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://python.org)\n[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/Version-2.0.0-orange.svg)](CHANGELOG.md)\n[![Framework Status](https://img.shields.io/badge/Status-Phase_2_Complete-brightgreen.svg)](docs/progress.md)\n\n\u003e 🎯 **接口驱动设计 + 组件注册系统 + 三层检索架构**\n\u003e 🚀 **生产就绪的企业级RAG框架**\n\n---\n\n## 📋 目录\n\n- [项目简介](#-项目简介)\n- [核心特性](#-核心特性)\n- [快速开始](#-快速开始)\n  - [安装指南](#安装指南)\n  - [5分钟快速上手](#5分钟快速上手)\n  - [环境配置](#环境配置)\n- [核心功能教程](#-核心功能教程)\n  - [三层检索系统](#1-三层检索系统)\n  - [MCP任务编排](#2-mcp任务编排)\n  - [智能模型选择](#3-智能模型选择bge分类器)\n  - [Few-Shot学习](#4-few-shot学习)\n- [完整示例](#-完整示例)\n- [配置详解](#-配置详解)\n- [进阶使用](#-进阶使用)\n- [性能优化](#-性能优化)\n- [常见问题](#-常见问题)\n- [项目架构](#-项目架构)\n- [文档索引](#-文档索引)\n- [贡献指南](#-贡献指南)\n- [许可证](#-许可证)\n\n---\n\n## 📖 项目简介\n\nDAML-RAG v2.0是一个**企业级RAG框架**，采用接口驱动设计和现代软件架构，为垂直领域AI应用提供生产就绪的解决方案。\n\n**核心设计理念**：接口驱动、组件化、可扩展、高性能。\n\n### 🏗️ v2.0架构革新\n\n#### 全新特性 ✅\n\n- **接口驱动设计**：5层标准接口体系，确保组件解耦和可替换性\n- **组件注册系统**：自动发现、依赖注入、生命周期管理\n- **三层检索架构**：语义检索→图谱检索→约束验证的渐进式精确化\n- **多模式向量引擎**：BGE-M3支持dense、sparse、colbert三种模式\n- **智能约束验证**：专业领域安全检查和质量保证系统\n- **多策略重排序**：动态权重融合和多样性优化算法\n\n#### 设计原则\n\n- **接口优先**：所有组件基于标准接口，支持热插拔替换\n- **异步编程**：全面采用async/await，提升并发性能\n- **类型安全**：完整的Python类型提示，减少运行时错误\n- **配置化**：支持YAML配置文件和环境变量覆盖\n- **可监控**：内置指标收集和性能监控\n\n---\n\n## 🎯 核心特性\n\n### 🏗️ 接口驱动架构\n\n- **🔧 5层标准接口体系**\n  - **基础接口**：`IComponent`, `IConfigurable`, `IMonitorable`\n  - **检索接口**：`IRetriever`, `ISemanticRetriever`, `IGraphRetriever`\n  - **编排接口**：`IOrchestrator`, `IToolRegistry`, `ITaskExecutor`\n  - **质量接口**：`IQualityChecker`, `IAntiHallucinationChecker`\n  - **存储接口**：`IVectorStorage`, `IGraphStorage`, `IDocumentStorage`\n\n### 🔍 三层检索引擎\n\n- **渐进式精确化架构**：语义→图谱→约束验证\n  - **语义检索层**：BGE-M3多模式向量匹配，支持dense/sparse/colbert\n  - **图谱检索层**：基于Neo4j的关系推理和路径发现\n  - **约束验证层**：专业安全规则和质量检查\n\n### 🧦 组件注册系统\n\n- **IoC容器**：支持单例、瞬态、作用域三种生命周期\n- **自动装配**：基于类型注解的依赖注入\n- **组件发现**：支持包扫描和装饰器注册\n- **配置管理**：分层次配置和热更新\n\n### 📦 存储抽象层\n\n- **统一接口**：屏蔽底层存储差异\n- **多种存储**：向量、图、文档、缓存、会话5种类型\n- **性能优化**：连接池、批量操作、重试机制\n- **监控支持**：内置指标收集和健康检查\n\n### ⚡ BGE-M3增强引擎\n\n- **多模式支持**：Dense、Sparse、ColBERT三种向量表示\n- **智能策略**：根据查询特征自动选择最优检索策略\n- **批量处理**：支持向量化编码和批量搜索\n- **缓存优化**：多级缓存提升重复查询性能\n\n### 🛡️ 智能约束验证\n\n- **多维度验证**：安全性、医疗性、专业规则、设备约束\n- **可配置规则**：支持动态规则加载和热更新\n- **风险评估**：多级风险等级和相应处理策略\n- **证据验证**：基于ACSM/NSCA等权威标准\n\n### 🔄 多策略重排序\n\n- **融合算法**：加权融合、倒数排名、Borda投票\n- **多样性优化**：保证结果多样性的同时提升质量\n- **个性化排序**：基于用户历史和偏好调整排序\n- **时效性考虑**：支持时间衰减和新鲜度提升\n\n---\n\n## 🚀 快速开始\n\n### 安装指南\n\n#### 方式1：从源码安装（当前推荐）\n\nDAML-RAG v2.0目前处于开发阶段，建议从源码安装：\n\n```bash\n# 1. 克隆仓库\ngit clone https://github.com/your-org/daml-rag-framework.git\ncd daml-rag-framework\n\n# 2. 创建虚拟环境\npython -m venv venv\nsource venv/bin/activate  # Linux/Mac\n# 或 venv\\Scripts\\activate  # Windows\n\n# 3. 安装依赖\npip install -r requirements.txt\n\n# 4. 开发模式安装\npip install -e .\n```\n\n#### 方式2：使用Docker\n\n```bash\n# 构建镜像\ndocker build -t daml-rag-framework:2.0 .\n\n# 运行容器\ndocker run -p 8000:8000 daml-rag-framework:2.0\n```\n\n---\n\n### 5分钟快速上手：v2.0框架\n\n#### 步骤1：创建项目目录\n\n```bash\nmkdir my-rag-app\ncd my-rag-app\n```\n\n#### 步骤2：编写基础代码\n\n创建 `main.py`：\n\n```python\nimport asyncio\nfrom daml_rag_framework import (\n    ThreeLayerRetriever, VectorRetriever, GraphRetriever,\n    ConstraintValidator, Reranker, QueryAnalyzer,\n    initialize_framework\n)\n\nasync def main():\n    print(\"🚀 初始化DAML-RAG框架 v2.0...\")\n\n    # 1. 初始化框架\n    config = {\n        'retrieval': {\n            'strategy': 'balanced',\n            'semantic_weight': 0.3,\n            'graph_weight': 0.5,\n            'constraint_weight': 0.2\n        },\n        'vector': {\n            'model_name': 'bge-m3',\n            'top_k': 10,\n            'min_similarity': 0.5,\n            'enable_cache': True\n        }\n    }\n\n    success = await initialize_framework(config)\n    if not success:\n        print(\"❌ 框架初始化失败\")\n        return\n\n    # 2. 创建组件\n    vector_retriever = VectorRetriever(\"vector_retriever\")\n    graph_retriever = GraphRetriever(\"graph_retriever\")\n    constraint_validator = ConstraintValidator(\"constraint_validator\")\n    reranker = Reranker(\"reranker\")\n    query_analyzer = QueryAnalyzer(\"query_analyzer\")\n\n    # 3. 配置三层检索引擎\n    three_layer_retriever = ThreeLayerRetriever(\"main_retriever\")\n    three_layer_retriever.set_semantic_retriever(vector_retriever)\n    three_layer_retriever.set_graph_retriever(graph_retriever)\n    three_layer_retriever.set_constraint_validator(constraint_validator)\n\n    # 4. 初始化组件\n    await vector_retriever.initialize(config.get('vector', {}))\n    await graph_retriever.initialize(config.get('graph', {}))\n    await constraint_validator.initialize(config.get('constraint', {}))\n    await reranker.initialize(config.get('reranking', {}))\n    await query_analyzer.initialize(config.get('analysis', {}))\n    await three_layer_retriever.initialize(config.get('retrieval', {}))\n\n    print(\"✅ 所有组件初始化完成\")\n\n    # 5. 处理查询\n    query = \"推荐5个不伤膝盖的腿部训练动作\"\n    print(f\"\\n🔍 处理查询: {query}\")\n\n    # 分析查询\n    analysis = await query_analyzer.analyze_query(query)\n    print(f\"📊 查询分析: {analysis.intent.value}, {analysis.complexity.value}\")\n    print(f\"🏷️  识别实体: {[(e, t.value) for e, t in analysis.entities]}\")\n\n    # 执行三层检索\n    from daml_rag_framework.interfaces.retrieval import QueryRequest\n    request = QueryRequest(\n        query_id=\"demo_001\",\n        query_text=query,\n        domain=\"fitness\",\n        top_k=5,\n        min_similarity=0.5,\n        mode=\"hybrid\"\n    )\n\n    response = await three_layer_retriever.retrieve(request)\n    print(f\"📋 检索结果: {len(response.results)} 个结果\")\n    print(f\"⏱️  执行时间: {response.execution_time:.3f}s\")\n\n    # 重排序结果\n    reranked = await reranker.rerank(response.results, request)\n    print(f\"🔄 重排序完成: {len(reranked.reranked_results)} 个结果\")\n\n    # 输出结果\n    print(\"\\n📝 推荐的训练动作:\")\n    for i, result in enumerate(reranked.reranked_results[:5], 1):\n        print(f\"{i}. {result.content[:50]}...\")\n        print(f\"   评分: {result.score:.3f}\")\n        print(f\"   来源: {result.metadata.get('source', 'unknown')}\")\n        print()\n\n    # 6. 显示统计信息\n    print(\"📊 组件统计:\")\n    print(f\"   向量检索器: {vector_retriever.get_metrics()}\")\n    print(f\"   图检索器: {graph_retriever.get_metrics()}\")\n    print(f\"   约束验证器: {constraint_validator.get_metrics()}\")\n    print(f\"   重排序器: {reranker.get_metrics()}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n#### 步骤3：创建配置文件\n\n创建 `config.yaml`：\n\n```yaml\n# DAML-RAG v2.0 配置示例\nframework:\n  name: \"daml_rag_v2\"\n  version: \"2.0.0\"\n  debug: true\n\nretrieval:\n  strategy: \"balanced\"\n  semantic_weight: 0.3\n  graph_weight: 0.5\n  constraint_weight: 0.2\n  enable_parallel: true\n\nvector:\n  model_name: \"BAAI/bge-m3\"\n  device: \"cpu\"  # 或 \"cuda\"\n  top_k: 20\n  min_similarity: 0.5\n  enable_cache: true\n  cache_ttl: 300\n\ngraph:\n  max_depth: 3\n  max_nodes: 100\n  enable_safety_filter: true\n  enable_evidence_filter: true\n  min_evidence_level: 0.5\n\nconstraint:\n  enable_safety_check: true\n  enable_domain_rules: true\n  enable_evidence_validation: true\n\nreranking:\n  primary_strategy: \"weighted_fusion\"\n  enable_diversity_promotion: true\n  diversity_threshold: 0.7\n  enable_recency_boost: true\n\nanalysis:\n  enable_intent_recognition: true\n  enable_entity_extraction: true\n  enable_relation_extraction: true\n```\n\n#### 步骤4：运行应用\n\n```bash\npython main.py\n```\n\n**预期输出**：\n\n```\n🚀 初始化DAML-RAG框架 v2.0...\n✅ 所有组件初始化完成\n\n🔍 处理查询: 推荐5个不伤膝盖的腿部训练动作\n📊 查询分析: recommendation, moderate\n🏷️  识别实体: [('腿部', 'muscle'), ('膝盖', 'injury'), ('训练', 'goal')]\n📋 检索结果: 8 个结果\n⏱️  执行时间: 1.234s\n🔄 重排序完成: 8 个结果\n\n📝 推荐的训练动作:\n1. 保加利亚分腿蹲 - 单腿训练动作，对膝盖压力小...\n   评分: 0.923\n   来源: vector_layer + graph_layer + constraint_layer\n\n2. 腿举 - 固定器械训练，安全性高...\n   评分: 0.889\n   来源: vector_layer + constraint_layer\n\n3. 臀桥 - 臀部训练，对膝盖友好...\n   评分: 0.876\n   来源: vector_layer + graph_layer\n\n📊 组件统计:\n   向量检索器: {'total_queries': 1, 'cache_hit_rate': 0.0, ...}\n   图检索器: {'total_queries': 1, 'path_discoveries': 2, ...}\n   约束验证器: {'total_validations': 8, 'safety_blocks': 1, ...}\n   重排序器: {'total_rerankings': 1, 'diversity_improvements': 1, ...}\n```\n\n---\n\n### 环境配置\n\n#### 最小环境要求\n\n| 资源 | 最低配置 | 推荐配置 |\n|------|---------|---------|\n| **Python** | 3.8+ | 3.10+ |\n| **内存** | 8GB | 16GB+ |\n| **存储** | 5GB | 20GB+ |\n| **CPU** | 4核 | 8核+ |\n\n#### 依赖服务\n\n##### 1. 向量数据库（选择一个）\n\n**Qdrant（推荐）**：\n\n```bash\n# Docker 部署\ndocker run -p 6333:6333 qdrant/qdrant\n\n# Python 客户端\npip install qdrant-client\n```\n\n**FAISS（本地）**：\n\n```bash\npip install faiss-cpu  # CPU版本\n# 或\npip install faiss-gpu  # GPU版本\n```\n\n##### 2. 图数据库（选择一个）\n\n**Neo4j（推荐）**：\n\n```bash\n# Docker 部署\ndocker run \\\n    -p 7474:7474 -p 7687:7687 \\\n    -e NEO4J_AUTH=neo4j/password \\\n    neo4j:latest\n\n# Python 客户端\npip install neo4j\n```\n\n##### 3. AI 模型服务\n\n**DeepSeek API（教师模型）**：\n\n```bash\n# 设置环境变量\nexport DEEPSEEK_API_KEY=\"your-api-key\"\n```\n\n**Ollama（学生模型，推荐）**：\n\n```bash\n# 安装 Ollama\ncurl -fsSL https://ollama.com/install.sh | sh\n\n# 拉取模型\nollama pull qwen2.5:7b\n\n# 启动服务\nollama serve\n```\n\n---\n\n## 📚 核心功能教程\n\n### 1. 三层检索系统\n\nDAML-RAG的核心创新：向量 + 图谱 + 规则的混合检索。\n\n#### 架构图\n\n```\n用户查询 \"推荐不伤膝盖的腿部增肌动作\"\n    ↓\n┌─────────────────────────────────────┐\n│ 第一层：向量语义检索                  │\n│ - 召回Top 20候选动作                  │\n│ - 语义理解：\"增肌\"=\"肥大训练\"          │\n│ - 耗时：~50ms                        │\n└──────────────┬──────────────────────┘\n               ↓\n┌─────────────────────────────────────┐\n│ 第二层：图关系推理                    │\n│ - 筛选：\"不伤膝盖\"约束                │\n│ - 关系推理：动作→肌群→目标             │\n│ - 耗时：~100ms                       │\n└──────────────┬──────────────────────┘\n               ↓\n┌─────────────────────────────────────┐\n│ 第三层：业务规则验证                  │\n│ - 安全规则：用户年龄、损伤史           │\n│ - 器械规则：可用设备                  │\n│ - 耗时：~20ms                        │\n└──────────────┬──────────────────────┘\n               ↓\n         精准结果 Top 5\n```\n\n#### 使用示例\n\n```python\nfrom daml_rag.retrieval import ThreeTierRetriever, RetrievalConfig\n\n# 配置检索系统\nconfig = RetrievalConfig(\n    vector_top_k=20,          # 向量召回数量\n    vector_threshold=0.6,     # 相似度阈值\n    graph_enabled=True,       # 启用图谱\n    graph_top_k=10,           # 图谱筛选数量\n    rules_enabled=True,       # 启用规则\n    cache_enabled=True,       # 启用缓存\n    cache_ttl=300            # 缓存5分钟\n)\n\n# 创建检索器\nretriever = ThreeTierRetriever(config)\nawait retriever.initialize()\n\n# 执行检索\nresults = await retriever.retrieve(\n    query=\"推荐不伤膝盖的腿部增肌动作\",\n    user_context={\n        \"user_id\": \"user123\",\n        \"age\": 35,\n        \"injury_history\": [\"knee_pain\"],\n        \"available_equipment\": [\"barbell\", \"dumbbell\"]\n    }\n)\n\n# 查看结果\nfor doc in results:\n    print(f\"动作: {doc.title}\")\n    print(f\"评分: {doc.score}\")\n    print(f\"来源: {doc.metadata['source']}\")\n    print(f\"推荐理由: {doc.metadata['reason']}\")\n    print(\"---\")\n```\n\n**输出示例**：\n\n```\n动作: 保加利亚分腿蹲\n评分: 0.92\n来源: vector_layer + graph_layer\n推荐理由: 单腿训练，减少膝盖压力，适合股四头肌增肌\n\n动作: 腿举\n评分: 0.89\n来源: vector_layer + graph_layer + rules\n推荐理由: 固定器械，安全性高，可调节膝盖角度\n\n动作: 罗马尼亚硬拉\n评分: 0.87\n来源: vector_layer + graph_layer\n推荐理由: 后链主导，对膝盖压力小，腘绳肌和臀部增肌\n...\n```\n\n---\n\n### 2. MCP任务编排\n\n基于Kahn拓扑排序的智能任务编排系统，支持并行执行和依赖管理。\n\n#### 核心概念\n\n- **DAG（有向无环图）**：任务之间的依赖关系\n- **拓扑排序**：确定任务执行顺序\n- **并行执行**：同一层级任务并发运行\n- **TTL缓存**：避免重复调用\n\n#### 使用示例\n\n```python\nfrom daml_rag.orchestration import MCPOrchestrator, Task, TaskStatus\n\n# 创建编排器\norchestrator = MCPOrchestrator(\n    metadata_db=my_db,\n    cache_ttl=300,           # 缓存5分钟\n    max_parallel=5,          # 最多并行5个任务\n    mcp_client_pool=pool     # MCP客户端池（可选）\n)\n\n# 定义任务\ntasks = [\n    # 任务1：获取用户档案（无依赖）\n    Task(\n        task_id=\"get_profile\",\n        mcp_server=\"fitness\",\n        tool_name=\"get_user_profile\",\n        params={\"user_id\": \"user123\"}\n    ),\n    \n    # 任务2：获取训练历史（无依赖）\n    Task(\n        task_id=\"get_history\",\n        mcp_server=\"fitness\",\n        tool_name=\"get_training_history\",\n        params={\"user_id\": \"user123\", \"days\": 30}\n    ),\n    \n    # 任务3：分析用户水平（依赖任务1和2）\n    Task(\n        task_id=\"analyze_level\",\n        mcp_server=\"coach\",\n        tool_name=\"analyze_user_level\",\n        params={\"user_id\": \"user123\"},\n        depends_on=[\"get_profile\", \"get_history\"]\n    ),\n    \n    # 任务4：生成训练计划（依赖任务3）\n    Task(\n        task_id=\"generate_plan\",\n        mcp_server=\"coach\",\n        tool_name=\"generate_workout_plan\",\n        params={\"user_id\": \"user123\"},\n        depends_on=[\"analyze_level\"]\n    )\n]\n\n# 执行编排\nresults = await orchestrator.execute(tasks, user_id=\"user123\")\n\n# 查看结果\nfor task_id, result in results.items():\n    print(f\"任务: {task_id}\")\n    print(f\"状态: {result.status}\")\n    print(f\"耗时: {result.elapsed_time}s\")\n    print(f\"结果: {result.data}\")\n    print(\"---\")\n\n# 获取执行统计\nsummary = orchestrator.get_execution_summary(tasks)\nprint(f\"总耗时: {summary['total_time']}s\")\nprint(f\"并行效率: {summary['parallel_efficiency']:.2f}x\")\nprint(f\"缓存命中率: {summary['cache_hit_rate']:.2%}\")\n```\n\n**输出示例**：\n\n```\n任务: get_profile\n状态: COMPLETED\n耗时: 0.5s\n结果: {'name': '张三', 'age': 35, 'level': 'intermediate'}\n---\n\n任务: get_history\n状态: COMPLETED\n耗时: 0.5s (并行执行)\n结果: {'workouts': 12, 'total_volume': 15000}\n---\n\n任务: analyze_level\n状态: COMPLETED\n耗时: 0.8s\n结果: {'level': 'intermediate', 'strengths': ['upper_body'], 'weaknesses': ['legs']}\n---\n\n任务: generate_plan\n状态: COMPLETED\n耗时: 1.2s\n结果: {'plan': {...}, 'duration': '8_weeks'}\n---\n\n总耗时: 3.0s\n并行效率: 2.17x (串行需6.5s)\n缓存命中率: 25%\n```\n\n#### 任务依赖关系图\n\n```\nget_profile ─────┐\n                 ├──\u003e analyze_level ──\u003e generate_plan\nget_history ─────┘\n\n执行顺序：\n第1层（并行）: get_profile, get_history\n第2层（串行）: analyze_level\n第3层（串行）: generate_plan\n```\n\n---\n\n### 3. 智能模型选择（BGE分类器）\n\n基于BAAI/bge-base-zh-v1.5向量模型的查询复杂度分类系统。\n\n#### 工作原理\n\n1. **预定义复杂查询模板**：\n   ```python\n   complex_queries = [\n       \"制定一个完整的训练计划\",\n       \"分析我的身体状况并给出建议\",\n       \"如何系统地提高力量水平\"\n   ]\n   ```\n\n2. **计算语义相似度**：\n   ```python\n   # 用户查询向量化\n   query_vec = bge_model.encode(user_query)\n   \n   # 计算与复杂模板的相似度\n   similarities = cosine_similarity(query_vec, complex_vecs)\n   max_sim = max(similarities)\n   ```\n\n3. **智能分类**：\n   ```python\n   if max_sim \u003e 0.7:\n       model = \"deepseek\"    # 复杂查询 → 教师模型\n   else:\n       model = \"ollama\"      # 简单查询 → 学生模型\n   ```\n\n#### 使用示例\n\n```python\nfrom daml_rag.learning import QueryComplexityClassifier\n\n# 创建分类器\nclassifier = QueryComplexityClassifier(\n    model_name=\"BAAI/bge-base-zh-v1.5\",\n    threshold=0.7,           # 复杂度阈值\n    cache_size=1000,         # 缓存大小\n    device=\"cuda\"            # 使用GPU（可选）\n)\n\n# 加载模型（懒加载，首次使用时自动加载）\nawait classifier.load_model()\n\n# 分类查询\nqueries = [\n    \"深蹲的标准动作\",                    # 简单查询\n    \"制定一个8周增肌训练计划\",            # 复杂查询\n    \"分析我的体态问题并给出纠正方案\"       # 复杂查询\n]\n\nfor query in queries:\n    is_complex = classifier.classify(query)\n    model = \"deepseek\" if is_complex else \"ollama\"\n    print(f\"查询: {query}\")\n    print(f\"分类: {'复杂' if is_complex else '简单'}\")\n    print(f\"推荐模型: {model}\")\n    print(\"---\")\n```\n\n**输出示例**：\n\n```\n查询: 深蹲的标准动作\n分类: 简单\n推荐模型: ollama\n相似度: 0.45\n成本: $0.001\n---\n\n查询: 制定一个8周增肌训练计划\n分类: 复杂\n推荐模型: deepseek\n相似度: 0.83\n成本: $0.02\n---\n\n查询: 分析我的体态问题并给出纠正方案\n分类: 复杂\n推荐模型: deepseek\n相似度: 0.76\n成本: $0.025\n---\n```\n\n#### 成本对比\n\n| 查询类型 | 模型选择 | 平均Token | 成本/次 | 质量评分 |\n|---------|---------|----------|---------|---------|\n| 简单查询 | Ollama | 500 | $0 | 4.2/5.0 |\n| 复杂查询 | DeepSeek | 2000 | $0.02 | 4.8/5.0 |\n| **混合策略** | **智能选择** | **800** | **$0.005** | **4.6/5.0** |\n\n**成本节省**: 相比全部使用DeepSeek，节省约 **75%** 成本。\n\n---\n\n### 4. Few-Shot学习\n\n基于经验记忆的上下文学习系统。\n\n#### 工作流程\n\n```\n用户查询 \"制定增肌计划\"\n    ↓\n1. 向量化查询\n    ↓\n2. 从经验库检索相似案例\n    ↓\n3. 筛选高质量经验（评分\u003e3.5）\n    ↓\n4. 注入Few-Shot上下文\n    ↓\n5. 生成高质量回答\n```\n\n#### 使用示例\n\n```python\nfrom daml_rag.learning import MemoryManager, Experience\n\n# 创建记忆管理器\nmemory = MemoryManager(\n    storage_type=\"redis\",      # 或 \"in_memory\"\n    max_experiences=1000,      # 最多存储1000条经验\n    similarity_threshold=0.7   # 相似度阈值\n)\n\n# 存储成功经验\nexperience = Experience(\n    query=\"如何增肌\",\n    context={\"user_level\": \"beginner\"},\n    response=\"建议从复合动作开始...\",\n    feedback_score=4.5,        # 用户评分\n    metadata={\n        \"model_used\": \"deepseek\",\n        \"tokens\": 520,\n        \"duration\": 2.3\n    }\n)\nawait memory.add_experience(experience)\n\n# 检索相似经验\nsimilar_exps = await memory.get_similar_experiences(\n    query=\"制定一个增肌训练计划\",\n    top_k=3,                   # 召回3个相似案例\n    min_score=3.5              # 最低评分要求\n)\n\n# 构建Few-Shot提示词\nfew_shot_prompt = \"\"\"\n以下是一些成功案例：\n\n案例1：\n用户问：{similar_exps[0].query}\n回答：{similar_exps[0].response}\n评分：{similar_exps[0].feedback_score}/5.0\n\n案例2：\n用户问：{similar_exps[1].query}\n回答：{similar_exps[1].response}\n评分：{similar_exps[1].feedback_score}/5.0\n\n现在请回答：\n用户问：{current_query}\n\"\"\"\n\n# 使用Few-Shot提示生成回答\nresponse = await llm.generate(few_shot_prompt)\n```\n\n#### 经验质量管理\n\n```python\n# 获取经验统计\nstats = memory.get_statistics()\nprint(f\"总经验数: {stats['total']}\")\nprint(f\"平均评分: {stats['avg_score']}\")\nprint(f\"高质量经验: {stats['high_quality']}\")\n\n# 清理低质量经验\nawait memory.cleanup(min_score=3.0, max_age_days=90)\n```\n\n---\n\n## 💼 完整示例\n\n### 示例1：健身领域AI助手\n\n```python\n\"\"\"\n完整的健身AI助手示例\n功能：训练计划生成、动作推荐、进度跟踪\n\"\"\"\nimport asyncio\nfrom daml_rag import DAMLRAGFramework, DAMLRAGConfig\nfrom daml_rag.adapters import FitnessDomainAdapter\n\nclass FitnessAICoach:\n    def __init__(self, config_path: str):\n        self.config = DAMLRAGConfig.from_file(config_path)\n        self.framework = None\n        self.adapter = None\n    \n    async def initialize(self):\n        \"\"\"初始化系统\"\"\"\n        # 创建领域适配器\n        self.adapter = FitnessDomainAdapter(\n            self.config.domain_config\n        )\n        await self.adapter.initialize()\n        \n        # 初始化框架\n        self.framework = DAMLRAGFramework(self.config)\n        await self.framework.initialize()\n        \n        print(\"✅ AI教练初始化完成\")\n    \n    async def generate_workout_plan(self, user_id: str, goal: str):\n        \"\"\"生成训练计划\"\"\"\n        query = f\"为我制定一个{goal}的训练计划\"\n        \n        result = await self.framework.process_query(\n            query=query,\n            user_context={\n                \"user_id\": user_id,\n                \"goal\": goal\n            }\n        )\n        \n        return {\n            \"plan\": result.response,\n            \"model_used\": result.model_used,\n            \"cost\": result.cost,\n            \"quality_score\": result.quality_score\n        }\n    \n    async def recommend_exercises(self, user_id: str, muscle_group: str):\n        \"\"\"推荐训练动作\"\"\"\n        query = f\"推荐5个{muscle_group}的训练动作\"\n        \n        result = await self.framework.process_query(\n            query=query,\n            user_context={\"user_id\": user_id}\n        )\n        \n        return result.response\n    \n    async def analyze_progress(self, user_id: str):\n        \"\"\"分析训练进度\"\"\"\n        # 使用MCP编排器协调多个工具\n        from daml_rag.orchestration import Task\n        \n        tasks = [\n            Task(\n                task_id=\"get_history\",\n                mcp_server=\"fitness\",\n                tool_name=\"get_training_history\",\n                params={\"user_id\": user_id, \"days\": 30}\n            ),\n            Task(\n                task_id=\"get_measurements\",\n                mcp_server=\"fitness\",\n                tool_name=\"get_body_measurements\",\n                params={\"user_id\": user_id}\n            ),\n            Task(\n                task_id=\"analyze\",\n                mcp_server=\"coach\",\n                tool_name=\"analyze_progress\",\n                params={\"user_id\": user_id},\n                depends_on=[\"get_history\", \"get_measurements\"]\n            )\n        ]\n        \n        results = await self.framework.orchestrator.execute(\n            tasks, user_id=user_id\n        )\n        \n        return results[\"analyze\"].data\n\n# 使用示例\nasync def main():\n    # 创建AI教练\n    coach = FitnessAICoach(\"config.yaml\")\n    await coach.initialize()\n    \n    # 生成训练计划\n    plan = await coach.generate_workout_plan(\n        user_id=\"user123\",\n        goal=\"增肌\"\n    )\n    print(f\"训练计划: {plan['plan']}\")\n    print(f\"使用模型: {plan['model_used']}\")\n    print(f\"成本: ${plan['cost']:.4f}\")\n    \n    # 推荐动作\n    exercises = await coach.recommend_exercises(\n        user_id=\"user123\",\n        muscle_group=\"胸部\"\n    )\n    print(f\"推荐动作: {exercises}\")\n    \n    # 分析进度\n    progress = await coach.analyze_progress(\"user123\")\n    print(f\"进度分析: {progress}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n### 示例2：医疗咨询AI助手\n\n```python\n\"\"\"\n医疗咨询AI助手示例\n功能：症状分析、用药建议、健康建议\n\"\"\"\nfrom daml_rag import DAMLRAGFramework, DAMLRAGConfig\n\nclass MedicalAIAssistant:\n    def __init__(self, config_path: str):\n        self.config = DAMLRAGConfig.from_file(config_path)\n        self.framework = None\n    \n    async def initialize(self):\n        self.framework = DAMLRAGFramework(self.config)\n        await self.framework.initialize()\n    \n    async def analyze_symptoms(self, symptoms: list, patient_info: dict):\n        \"\"\"分析症状\"\"\"\n        query = f\"患者症状：{', '.join(symptoms)}，请分析可能的原因\"\n        \n        result = await self.framework.process_query(\n            query=query,\n            user_context=patient_info\n        )\n        \n        return {\n            \"analysis\": result.response,\n            \"confidence\": result.quality_score,\n            \"references\": result.retrieved_docs\n        }\n    \n    async def suggest_medication(self, condition: str, patient_info: dict):\n        \"\"\"用药建议\"\"\"\n        # 医疗领域必须使用高质量模型\n        result = await self.framework.process_query(\n            query=f\"针对{condition}，推荐合适的用药方案\",\n            user_context=patient_info,\n            force_teacher_model=True  # 强制使用教师模型\n        )\n        \n        return result.response\n\n# 使用示例\nasync def main():\n    assistant = MedicalAIAssistant(\"medical_config.yaml\")\n    await assistant.initialize()\n    \n    # 分析症状\n    analysis = await assistant.analyze_symptoms(\n        symptoms=[\"头痛\", \"发热\", \"咳嗽\"],\n        patient_info={\n            \"age\": 35,\n            \"gender\": \"male\",\n            \"medical_history\": [\"哮喘\"]\n        }\n    )\n    print(f\"分析结果: {analysis['analysis']}\")\n    print(f\"置信度: {analysis['confidence']}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\n---\n\n## ⚙️ 配置详解\n\n### 完整配置文件\n\n```yaml\n# config.yaml - DAML-RAG 完整配置示例\n\n# ========================================\n# 基础配置\n# ========================================\ndomain: fitness                    # 领域：fitness, medical, legal, etc.\ndebug: true                        # 调试模式\nlog_level: INFO                    # 日志级别：DEBUG, INFO, WARNING, ERROR\nlog_file: logs/app.log            # 日志文件路径\n\n# ========================================\n# 检索系统配置\n# ========================================\nretrieval:\n  # 向量检索配置\n  vector_model: \"BAAI/bge-base-zh-v1.5\"  # 向量模型\n  vector_store: \"qdrant\"                  # 向量数据库：qdrant, faiss, milvus\n  vector_host: \"localhost\"\n  vector_port: 6333\n  vector_top_k: 20                        # 召回数量\n  vector_threshold: 0.6                   # 相似度阈值\n  vector_weight: 0.3                      # 向量层权重\n  \n  # 知识图谱配置\n  graph_enabled: true                     # 是否启用图谱\n  graph_store: \"neo4j\"                    # 图数据库：neo4j, arangodb\n  graph_uri: \"bolt://localhost:7687\"\n  graph_user: \"neo4j\"\n  graph_password: \"password\"\n  graph_top_k: 10                         # 图谱筛选数量\n  graph_weight: 0.5                       # 图谱层权重\n  \n  # 规则引擎配置\n  rules_enabled: true                     # 是否启用规则\n  rules_path: \"rules/\"                    # 规则文件目录\n  rules_weight: 0.2                       # 规则层权重\n  \n  # 缓存配置\n  cache_enabled: true                     # 是否启用缓存\n  cache_ttl: 300                          # 缓存过期时间（秒）\n  cache_backend: \"redis\"                  # 缓存后端：redis, memory\n  cache_host: \"localhost\"\n  cache_port: 6379\n  \n  # 性能配置\n  total_timeout: 5.0                      # 总超时时间（秒）\n  vector_timeout: 1.0                     # 向量检索超时\n  graph_timeout: 2.0                      # 图谱检索超时\n  rules_timeout: 0.5                      # 规则过滤超时\n\n# ========================================\n# 任务编排配置\n# ========================================\norchestration:\n  max_parallel_tasks: 10                  # 最大并行任务数\n  max_parallel_workflows: 5               # 最大并行工作流数\n  timeout_seconds: 30                     # 工作流超时（秒）\n  retry_attempts: 3                       # 重试次数\n  retry_delay: 1.0                        # 重试延迟（秒）\n  enable_caching: true                    # 启用任务缓存\n  cache_ttl: 300                          # 任务缓存TTL\n  enable_monitoring: true                 # 启用监控\n\n# ========================================\n# 学习系统配置\n# ========================================\nlearning:\n  # 模型配置\n  teacher_model: \"deepseek\"               # 教师模型\n  student_model: \"ollama-qwen2.5\"         # 学生模型\n  teacher_api_key: \"${DEEPSEEK_API_KEY}\"  # 环境变量\n  student_endpoint: \"http://localhost:11434\"\n  \n  # BGE分类器配置\n  classifier_model: \"BAAI/bge-base-zh-v1.5\"\n  classifier_threshold: 0.7               # 复杂度阈值\n  classifier_cache_size: 1000             # 分类缓存大小\n  \n  # 经验记忆配置\n  memory_backend: \"redis\"                 # memory, redis\n  memory_host: \"localhost\"\n  memory_port: 6379\n  max_experiences: 10000                  # 最大经验数\n  experience_threshold: 3.5               # 经验质量阈值\n  \n  # Few-Shot配置\n  few_shot_enabled: true                  # 启用Few-Shot\n  few_shot_count: 3                       # Few-Shot示例数量\n  similarity_threshold: 0.7               # 经验相似度阈值\n  \n  # 质量控制配置\n  quality_check_enabled: true             # 启用质量检查\n  quality_threshold: 3.5                  # 质量阈值\n  auto_upgrade: true                      # 自动升级到教师模型\n  \n  # 反馈配置\n  feedback_enabled: true                  # 启用用户反馈\n  feedback_weight: 0.8                    # 反馈权重\n  adaptive_threshold: 0.7                 # 自适应阈值\n\n# ========================================\n# 领域适配器配置\n# ========================================\ndomain_config:\n  # 知识图谱\n  knowledge_graph_path: \"./data/kg.db\"\n  kg_entities_count: 2447                 # 实体数量\n  kg_relationships_count: 5892            # 关系数量\n  \n  # MCP服务器\n  mcp_servers:\n    - name: \"user-profile\"\n      command: \"python\"\n      args: [\"servers/user-profile/server.py\"]\n      env:\n        DB_PATH: \"./data/users.db\"\n    \n    - name: \"professional-coach\"\n      command: \"python\"\n      args: [\"servers/coach/server.py\"]\n      env:\n        MODEL_PATH: \"./models/coach\"\n  \n  # 领域规则\n  domain_rules:\n    safety_rules:\n      - age_check\n      - injury_check\n      - medical_clearance\n    \n    business_rules:\n      - equipment_availability\n      - facility_constraints\n      - time_constraints\n\n# ========================================\n# 监控配置\n# ========================================\nmonitoring:\n  enabled: true                           # 启用监控\n  prometheus_port: 9090                   # Prometheus端口\n  grafana_enabled: true                   # 启用Grafana\n  metrics_interval: 60                    # 指标采集间隔（秒）\n  \n  # 告警配置\n  alerting:\n    enabled: true\n    email: \"admin@example.com\"\n    slack_webhook: \"${SLACK_WEBHOOK}\"\n    \n    # 告警规则\n    rules:\n      - name: \"high_latency\"\n        condition: \"avg_latency \u003e 5s\"\n        severity: \"warning\"\n      \n      - name: \"low_quality\"\n        condition: \"avg_quality \u003c 3.0\"\n        severity: \"critical\"\n\n# ========================================\n# 安全配置\n# ========================================\nsecurity:\n  api_key_required: true                  # 需要API密钥\n  rate_limiting:\n    enabled: true                         # 启用速率限制\n    requests_per_minute: 60               # 每分钟请求数\n    requests_per_hour: 1000               # 每小时请求数\n  \n  cors:\n    enabled: true                         # 启用CORS\n    allowed_origins:\n      - \"http://localhost:3000\"\n      - \"https://yourdomain.com\"\n```\n\n### 配置优先级\n\n1. **环境变量** \u003e 2. **配置文件** \u003e 3. **默认值**\n\n```python\n# 使用环境变量覆盖配置\nimport os\nos.environ[\"DEEPSEEK_API_KEY\"] = \"your-key\"\nos.environ[\"DAML_RAG_DEBUG\"] = \"true\"\n\n# 加载配置时自动应用环境变量\nconfig = DAMLRAGConfig.from_file(\"config.yaml\")\n```\n\n---\n\n## 🎓 进阶使用\n\n### 1. 自定义领域适配器\n\n```python\nfrom daml_rag.adapters.base import BaseDomainAdapter\n\nclass LegalDomainAdapter(BaseDomainAdapter):\n    \"\"\"法律领域适配器\"\"\"\n    \n    async def initialize(self):\n        \"\"\"初始化法律知识库\"\"\"\n        # 加载法律条文\n        self.legal_codes = await self.load_legal_codes()\n        \n        # 加载判例库\n        self.cases = await self.load_cases()\n        \n        # 初始化法律术语词典\n        self.legal_terms = await self.load_legal_terms()\n    \n    async def preprocess_query(self, query: str) -\u003e str:\n        \"\"\"预处理查询\"\"\"\n        # 识别法律术语\n        terms = self.extract_legal_terms(query)\n        \n        # 扩展查询\n        expanded_query = self.expand_with_synonyms(query, terms)\n        \n        return expanded_query\n    \n    async def postprocess_response(self, response: str) -\u003e str:\n        \"\"\"后处理响应\"\"\"\n        # 添加法律条文引用\n        response_with_refs = self.add_legal_references(response)\n        \n        # 添加免责声明\n        response_with_disclaimer = self.add_disclaimer(\n            response_with_refs\n        )\n        \n        return response_with_disclaimer\n    \n    def load_domain_rules(self) -\u003e List[Rule]:\n        \"\"\"加载领域规则\"\"\"\n        return [\n            Rule(\n                name=\"legal_age_check\",\n                condition=lambda ctx: ctx.get(\"age\", 0) \u003e= 18,\n                message=\"法律咨询仅限成年人使用\"\n            ),\n            Rule(\n                name=\"jurisdiction_check\",\n                condition=lambda ctx: ctx.get(\"jurisdiction\") in self.supported_jurisdictions,\n                message=\"该地区法律咨询暂不支持\"\n            )\n        ]\n```\n\n### 2. 自定义规则引擎\n\n```python\nfrom daml_rag.retrieval.rules import Rule, RuleEngine, RuleContext\n\n# 创建自定义规则\nclass SafetyRule(Rule):\n    \"\"\"安全规则\"\"\"\n    \n    def __init__(self):\n        super().__init__(\n            name=\"safety_check\",\n            priority=10  # 高优先级\n        )\n    \n    def evaluate(self, context: RuleContext) -\u003e bool:\n        \"\"\"评估规则\"\"\"\n        # 检查年龄\n        if context.user_age \u003c 18:\n            return False\n        \n        # 检查损伤史\n        if \"serious_injury\" in context.injury_history:\n            return False\n        \n        # 检查医疗许可\n        if not context.medical_clearance:\n            return False\n        \n        return True\n    \n    def get_reason(self, context: RuleContext) -\u003e str:\n        \"\"\"获取规则说明\"\"\"\n        if context.user_age \u003c 18:\n            return \"未成年人需要监护人陪同\"\n        if \"serious_injury\" in context.injury_history:\n            return \"严重损伤史，请先咨询医生\"\n        if not context.medical_clearance:\n            return \"需要医疗许可才能进行训练\"\n        return \"\"\n\n# 使用自定义规则\nengine = RuleEngine()\nengine.add_rule(SafetyRule())\nengine.add_rule(EquipmentRule())\nengine.add_rule(TimeConstraintRule())\n\n# 评估规则\ncontext = RuleContext(\n    user_age=35,\n    injury_history=[],\n    medical_clearance=True,\n    available_equipment=[\"barbell\", \"dumbbell\"]\n)\n\npassed, reasons = engine.evaluate_all(context)\nif not passed:\n    print(f\"规则未通过: {reasons}\")\n```\n\n### 3. 自定义向量检索器\n\n```python\nfrom daml_rag.retrieval.vector.base import BaseVectorRetriever\nimport numpy as np\n\nclass CustomVectorRetriever(BaseVectorRetriever):\n    \"\"\"自定义向量检索器\"\"\"\n    \n    def __init__(self, config):\n        super().__init__(config)\n        self.model = None\n        self.index = None\n    \n    async def initialize(self):\n        \"\"\"初始化检索器\"\"\"\n        # 加载向量模型\n        from sentence_transformers import SentenceTransformer\n        self.model = SentenceTransformer(self.config.model_name)\n        \n        # 加载向量索引\n        import faiss\n        self.index = faiss.read_index(self.config.index_path)\n    \n    async def encode(self, text: str) -\u003e np.ndarray:\n        \"\"\"文本向量化\"\"\"\n        return self.model.encode(text)\n    \n    async def search(self, query: str, top_k: int = 10) -\u003e List[Document]:\n        \"\"\"检索相似文档\"\"\"\n        # 查询向量化\n        query_vec = await self.encode(query)\n        \n        # FAISS检索\n        distances, indices = self.index.search(\n            query_vec.reshape(1, -1),\n            top_k\n        )\n        \n        # 构造结果\n        results = []\n        for idx, dist in zip(indices[0], distances[0]):\n            doc = await self.load_document(idx)\n            doc.score = 1 / (1 + dist)  # 转换距离为相似度\n            results.append(doc)\n        \n        return results\n```\n\n### 4. 监控和告警\n\n```python\nfrom daml_rag.monitoring import MetricsCollector, AlertManager\n\n# 创建指标收集器\nmetrics = MetricsCollector()\n\n# 记录请求\n@metrics.track_request\nasync def process_query(query: str):\n    result = await framework.process_query(query)\n    \n    # 记录指标\n    metrics.record_latency(result.elapsed_time)\n    metrics.record_tokens(result.tokens)\n    metrics.record_cost(result.cost)\n    metrics.record_quality(result.quality_score)\n    \n    return result\n\n# 创建告警管理器\nalert_manager = AlertManager(config.alerting)\n\n# 检查指标并发送告警\nif metrics.avg_latency \u003e 5.0:\n    await alert_manager.send_alert(\n        severity=\"warning\",\n        message=f\"平均延迟过高: {metrics.avg_latency}s\",\n        channel=\"slack\"\n    )\n\nif metrics.avg_quality \u003c 3.0:\n    await alert_manager.send_alert(\n        severity=\"critical\",\n        message=f\"平均质量过低: {metrics.avg_quality}\",\n        channel=\"email\"\n    )\n```\n\n---\n\n## 🚀 性能优化\n\n### 1. 缓存策略\n\n```python\n# 多级缓存配置\nretrieval:\n  # L1缓存：内存缓存（最快）\n  l1_cache:\n    enabled: true\n    max_size: 1000\n    ttl: 60  # 1分钟\n  \n  # L2缓存：Redis缓存\n  l2_cache:\n    enabled: true\n    host: \"localhost\"\n    port: 6379\n    ttl: 300  # 5分钟\n  \n  # L3缓存：向量数据库缓存\n  l3_cache:\n    enabled: true\n    ttl: 3600  # 1小时\n```\n\n### 2. 并行优化\n\n```python\n# 启用并行检索\nretrieval:\n  parallel_enabled: true\n  max_workers: 10           # 最大并行数\n\n# 启用并行MCP调用\norchestration:\n  parallel_enabled: true\n  max_parallel: 5           # 最大并行任务数\n```\n\n### 3. 连接池\n\n```python\nfrom daml_rag.utils import ConnectionPool\n\n# 创建连接池\npool = ConnectionPool(\n    pool_size=10,              # 连接池大小\n    max_overflow=5,            # 最大溢出连接\n    pool_timeout=30,           # 获取连接超时\n    pool_recycle=3600          # 连接回收时间\n)\n\n# 使用连接池\nasync with pool.acquire() as conn:\n    result = await conn.execute(query)\n```\n\n### 4. 批处理\n\n```python\n# 批量处理查询\nasync def process_batch(queries: List[str]):\n    # 批量向量化\n    vectors = await retriever.encode_batch(queries)\n    \n    # 批量检索\n    results = await retriever.search_batch(vectors)\n    \n    # 批量生成\n    responses = await llm.generate_batch(results)\n    \n    return responses\n```\n\n### 5. 性能监控\n\n```python\nfrom daml_rag.profiling import Profiler\n\n# 启用性能分析\nprofiler = Profiler(enabled=True)\n\nwith profiler.profile(\"query_processing\"):\n    result = await framework.process_query(query)\n\n# 查看性能报告\nreport = profiler.get_report()\nprint(f\"总耗时: {report.total_time}s\")\nprint(f\"检索耗时: {report.retrieval_time}s\")\nprint(f\"生成耗时: {report.generation_time}s\")\n```\n\n---\n\n## ❓ 常见问题\n\n### Q1: 安装失败怎么办？\n\n**A**: 常见解决方案：\n\n```bash\n# 方案1：升级pip\npython -m pip install --upgrade pip\n\n# 方案2：使用国内镜像\npip install -i https://pypi.tuna.tsinghua.edu.cn/simple daml-rag-framework\n\n# 方案3：从源码安装\ngit clone https://github.com/vivy1024/daml-rag-framework.git\ncd daml-rag-framework\npip install -e .\n```\n\n### Q2: 如何减少响应时间？\n\n**A**: 优化策略：\n\n1. **启用缓存**：\n```yaml\nretrieval:\n  cache_enabled: true\n  cache_backend: \"redis\"  # 比内存缓存更快\n```\n\n2. **启用并行**：\n```yaml\norchestration:\n  max_parallel_tasks: 10\n```\n\n3. **优化向量检索**：\n```yaml\nretrieval:\n  vector_top_k: 10  # 减少召回数量\n  vector_threshold: 0.7  # 提高阈值\n```\n\n### Q3: 如何降低成本？\n\n**A**: 成本优化：\n\n1. **启用BGE分类器**：\n```yaml\nlearning:\n  classifier_enabled: true\n  classifier_threshold: 0.7\n```\n\n2. **优先使用学生模型**：\n```yaml\nlearning:\n  student_model_priority: true\n  quality_threshold: 3.0  # 降低质量要求\n```\n\n3. **启用缓存**：\n```yaml\nlearning:\n  memory_backend: \"redis\"\n  cache_ttl: 3600  # 长缓存时间\n```\n\n### Q4: 如何提高质量？\n\n**A**: 质量提升：\n\n1. **启用Few-Shot学习**：\n```yaml\nlearning:\n  few_shot_enabled: true\n  few_shot_count: 5  # 增加示例数量\n```\n\n2. **提高质量阈值**：\n```yaml\nlearning:\n  quality_threshold: 4.0\n  auto_upgrade: true  # 自动升级\n```\n\n3. **使用教师模型**：\n```python\nresult = await framework.process_query(\n    query=query,\n    force_teacher_model=True  # 强制使用教师模型\n)\n```\n\n### Q5: 如何处理大规模数据？\n\n**A**: 扩展方案：\n\n1. **分布式部署**：\n```yaml\ndeployment:\n  mode: \"distributed\"\n  nodes:\n    - host: \"node1\"\n      port: 8000\n    - host: \"node2\"\n      port: 8000\n```\n\n2. **数据分片**：\n```python\n# 按领域分片\nshards = {\n    \"fitness\": Shard(\"fitness_db\"),\n    \"medical\": Shard(\"medical_db\"),\n    \"legal\": Shard(\"legal_db\")\n}\n```\n\n3. **使用专业数据库**：\n```yaml\nretrieval:\n  vector_store: \"milvus\"  # 支持百亿级向量\n  graph_store: \"janusgraph\"  # 分布式图数据库\n```\n\n### Q6: 如何调试问题？\n\n**A**: 调试技巧：\n\n```python\n# 启用调试模式\nconfig = DAMLRAGConfig.from_file(\"config.yaml\")\nconfig.debug = True\nconfig.log_level = \"DEBUG\"\n\n# 查看详细日志\nimport logging\nlogging.basicConfig(level=logging.DEBUG)\n\n# 使用Profiler定位性能瓶颈\nfrom daml_rag.profiling import Profiler\nprofiler = Profiler(enabled=True)\n```\n\n### Q7: 支持哪些数据库？\n\n**A**: 支持列表：\n\n| 类型 | 支持的数据库 | 推荐 |\n|------|------------|------|\n| **向量数据库** | Qdrant, FAISS, Milvus, Pinecone, Weaviate | Qdrant |\n| **图数据库** | Neo4j, ArangoDB, JanusGraph, Neptune | Neo4j |\n| **缓存数据库** | Redis, Memcached, 内存 | Redis |\n| **关系数据库** | PostgreSQL, MySQL, SQLite | PostgreSQL |\n\n---\n\n## 🏗️ 项目架构\n\n### 模块结构\n\n```\ndaml-rag-framework/\n├── daml_rag/                      # 核心包\n│   ├── __init__.py               # 包入口\n│   ├── core.py                   # 核心框架\n│   ├── base.py                   # 基础类\n│   │\n│   ├── retrieval/                # 🔍 检索模块\n│   │   ├── __init__.py\n│   │   ├── three_tier.py        # 三层检索系统\n│   │   ├── vector/              # 向量检索\n│   │   │   ├── base.py          # 基础类\n│   │   │   ├── qdrant.py        # Qdrant实现\n│   │   │   ├── faiss.py         # FAISS实现\n│   │   │   └── qdrant.py        # Milvus实现\n│   │   ├── knowledge/           # 知识图谱\n│   │   │   ├── __init__.py\n│   │   │   └── neo4j.py         # Neo4j实现\n│   │   └── rules/               # 规则引擎\n│   │       ├── __init__.py\n│   │       └── engine.py        # 规则引擎实现\n│   │\n│   ├── orchestration/            # 🎯 任务编排\n│   │   ├── __init__.py\n│   │   ├── orchestrator.py      # 通用编排器\n│   │   └── mcp_orchestrator.py  # MCP编排器(v1.2.0)\n│   │\n│   ├── learning/                 # 🧠 学习模块\n│   │   ├── __init__.py\n│   │   ├── memory.py            # 经验记忆\n│   │   ├── model_provider.py    # 模型提供者\n│   │   ├── query_classifier.py  # BGE分类器(v1.1.0)\n│   │   ├── feedback.py          # 反馈系统\n│   │   └── adaptation.py        # 自适应学习\n│   │\n│   ├── adapters/                 # 🔌 领域适配器\n│   │   ├── __init__.py\n│   │   ├── base/\n│   │   │   └── adapter.py       # 基础适配器\n│   │   └── fitness/\n│   │       └── fitness_adapter.py  # 健身适配器\n│   │\n│   ├── config/                   # ⚙️ 配置管理\n│   │   ├── __init__.py\n│   │   └── framework_config.py\n│   │\n│   ├── interfaces/               # 📋 接口定义\n│   │   ├── __init__.py\n│   │   ├── retrieval.py\n│   │   ├── orchestration.py\n│   │   └── learning.py\n│   │\n│   ├── models/                   # 📊 数据模型\n│   │   ├── __init__.py\n│   │   └── base.py\n│   │\n│   └── cli/                      # 🚀 命令行工具\n│       ├── __init__.py\n│       └── cli.py\n│\n├── examples/                      # 📚 示例代码\n│   ├── fitness_qa_demo.py\n│   ├── mcp_orchestrator_example.py\n│   └── config_examples.py\n│\n├── docs/                          # 📖 文档\n│   ├── theory/                   # 理论文档\n│   ├── architecture/             # 架构文档\n│   └── quickstart.md            # 快速开始\n│\n├── tests/                         # ✅ 测试\n│   ├── test_retrieval.py\n│   ├── test_orchestration.py\n│   └── test_learning.py\n│\n├── scripts/                       # 🔧 脚本\n│   ├── build.sh\n│   ├── publish.sh\n│   └── test-install.sh\n│\n├── docker/                        # 🐳 Docker配置\n│   ├── Dockerfile\n│   └── docker-compose.yml\n│\n├── pyproject.toml                # 📦 项目配置\n├── requirements.txt              # 依赖列表\n├── README.md                     # 本文件\n├── CHANGELOG.md                  # 变更日志\n├── LICENSE                       # 许可证\n└── CITATION.cff                  # 引用信息\n```\n\n### 三层检索架构\n\n```\n┌──────────────────────────────────────────────────────────┐\n│                     用户查询输入                           │\n└────────────────────┬─────────────────────────────────────┘\n                     ↓\n┌──────────────────────────────────────────────────────────┐\n│  第一层：向量语义检索 (Vector Retrieval)                   │\n│  ✅ 快速召回候选集（Top 20-50）                            │\n│  ✅ 语义相似度匹配                                         │\n│  ✅ 支持多种向量数据库                                     │\n└────────────────────┬─────────────────────────────────────┘\n                     ↓\n┌──────────────────────────────────────────────────────────┐\n│  第二层：图关系推理 (Knowledge Graph)                      │\n│  ✅ 精确关系筛选                                           │\n│  ✅ 多跳推理能力                                           │\n│  ✅ 可解释性强                                            │\n└────────────────────┬─────────────────────────────────────┘\n                     ↓\n┌──────────────────────────────────────────────────────────┐\n│  第三层：业务规则验证 (Rule Filtering)                     │\n│  ✅ 安全规则验证                                           │\n│  ✅ 业务逻辑过滤                                           │\n│  ✅ 个性化推荐                                            │\n└────────────────────┬─────────────────────────────────────┘\n                     ↓\n              精准结果 Top 5\n```\n\n---\n\n## 📚 文档索引\n\n### 核心文档\n\n- **[LIMITATIONS.md](LIMITATIONS.md)** ⚠️ - 限制和约束（必读！）\n- **[PUBLISHING.md](PUBLISHING.md)** 📦 - PyPI 发布指南\n- **[CHANGELOG.md](CHANGELOG.md)** 📝 - 版本变更历史\n- **[CONTRIBUTING.md](CONTRIBUTING.md)** 🤝 - 贡献指南\n- **[LICENSE](LICENSE)** 📄 - Apache 2.0许可证\n\n### API文档 📖\n\n- **[快速开始指南](docs/quickstart.md)** - 5分钟快速上手\n- **[框架API参考](docs/api/framework.md)** - 核心框架API\n- **[检索系统API](docs/api/retrieval.md)** - 三层检索系统API\n- **[编排系统API](docs/api/orchestration.md)** - MCP任务编排API\n- **[学习系统API](docs/api/learning.md)** - 智能学习系统API\n- **[配置参考](docs/api/configuration.md)** - 完整配置说明\n\n### 理论文档\n\n- [理论演进历史](docs/theory/00-理论演进历史.md) ([English](docs/theory/00-THEORY_EVOLUTION.md))\n- [GraphRAG混合检索理论](docs/theory/01-GraphRAG混合检索理论.md)\n- [推理时上下文学习理论](docs/theory/02-推理时上下文学习理论.md)\n- [框架总览](docs/theory/框架总览.md)\n\n### 架构文档 ⭐\n\n- [MCP编排器实际实现](docs/architecture/mcp-orchestration-实际实现.md)\n- [数据清洗与微调架构](docs/architecture/数据清洗与微调架构.md)\n- [框架多样性探索策略](docs/architecture/框架多样性探索策略.md)\n\n### 发布说明\n\n- [v1.2.0 发布说明](RELEASE_NOTES_v1.2.0.md) - MCP编排器 + 目录清理\n- [v1.1.0 发布说明](RELEASE_NOTES.md) - BGE智能分类器\n\n---\n\n## 📊 项目状态\n\n**⚠️ 项目状态：生产准备（前端完善中）**\n\n### 实际测量数据\n\n| 指标 | 当前值 | 说明 |\n|------|-------|------|\n| **Token/查询（简单）** | 500-800 | DeepSeek + 用户档案MCP |\n| **响应时间** | **~20秒** | ⚠️ 未优化，需要缓存 |\n| **项目阶段** | 生产准备 | 准备部署中 |\n| **MCP工具实现** | 14/14 ✅ | 所有工具已完成 |\n| **Docker状态** | 使用中 | 本地部署就绪 |\n| **前端状态** | 进行中 | 部署前完善 |\n\n### 当前问题\n\n**⚠️ 已知性能问题：**\n\n- **响应缓慢**：简单查询约20秒\n  - 原因：未优化的图查询，无缓存机制\n  - 原因：多个串行MCP调用，无并行化\n  - 状态：第一阶段计划优化\n  \n- **前端完善**：进行中\n  - 工具后端：✅ 完成（14/14）\n  - 前端UI：🚧 完善中\n  - Docker部署：✅ 本地就绪\n\n### 已知限制\n\n**⚠️ 重要：使用前请阅读 [LIMITATIONS.md](LIMITATIONS.md)！**\n\n关键限制：\n\n- **硬件需求**：最低16GB内存，推荐32GB+\n- **响应时间**：~20秒（玉珍健身笔记本案例，未优化）\n- **规模限制**：单机超过30K节点性能下降\n- **部署**：生产环境建议分布式部署\n\n---\n\n## 🤝 贡献指南\n\n欢迎贡献！贡献方式：\n\n### 1. 报告问题\n\n在 [GitHub Issues](https://github.com/vivy1024/daml-rag-framework/issues) 提交：\n\n- Bug报告\n- 功能请求\n- 文档改进建议\n\n### 2. 提交代码\n\n```bash\n# 1. Fork 项目\n# 2. 创建特性分支\ngit checkout -b feature/your-feature\n\n# 3. 提交更改\ngit commit -m \"Add: your feature description\"\n\n# 4. 推送到分支\ngit push origin feature/your-feature\n\n# 5. 创建 Pull Request\n```\n\n### 3. 改进文档\n\n- 修正错误\n- 添加示例\n- 翻译文档\n\n### 4. 分享案例\n\n- 分享使用经验\n- 提供领域适配器\n- 贡献示例代码\n\n---\n\n## 📖 学术引用\n\n如果您在研究或项目中使用DAML-RAG，请引用：\n\n```bibtex\n@software{daml_rag_2025,\n  title={DAML-RAG: Domain-Adaptive Meta-Learning RAG Framework},\n  author={薛小川 (Xue Xiaochuan)},\n  year={2025},\n  version={1.2.0},\n  url={https://github.com/vivy1024/daml-rag-framework},\n  doi={待分配}\n}\n```\n\n详见 [CITATION.cff](CITATION.cff) 获取完整引用元数据。\n\n---\n\n## 📄 许可证\n\n**版权所有 © 2025 薛小川。保留所有权利。**\n\n根据Apache License 2.0许可证授权。您可以在以下网址获取许可证副本：\n\n    http://www.apache.org/licenses/LICENSE-2.0\n\n除非适用法律要求或书面同意，否则根据许可证分发的软件按\"原样\"分发，不附带任何明示或暗示的担保或条件。详见 [LICENSE](LICENSE) 文件。\n\n---\n\n## 🙏 致谢\n\n基于玉珍健身 v2.0项目的理论和实践成果构建。\n\n**站在巨人的肩膀上：**\n\n- **RAG**: Lewis et al. (2020)\n- **GraphRAG**: Microsoft Research (2025)\n- **In-Context Learning**: Brown et al. (2020)\n- **Knowledge Graph**: Hogan et al. (2021)\n- **MCP Protocol**: Anthropic (2025)\n- **BGE Model**: Beijing Academy of AI (BAAI)\n\n---\n\n## 📞 联系方式\n\n- **作者**: 薛小川 (Xue Xiaochuan)\n- **邮箱**: 1765563156@qq.com\n- **GitHub**: https://github.com/vivy1024/daml-rag-framework\n- **PyPI**: https://pypi.org/project/daml-rag-framework/\n- **问题反馈**: https://github.com/vivy1024/daml-rag-framework/issues\n\n---\n\n**让AI更懂专业领域** 🚀\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivy1024%2Fdaml-rag-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvivy1024%2Fdaml-rag-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvivy1024%2Fdaml-rag-framework/lists"}