QueryMind

具有智能查询路由、语义搜索和网页回退功能的多智能体RAG系统

![Python 3.9+](https://www.python.org/downloads/) ![License: MIT](https://opensource.org/licenses/MIT) ![Tests](./tests) ![Code style: black](https://github.com/psf/black)

QueryMind是一个轻量级、可直接投入生产的检索增强生成（RAG）系统，它结合了ChromaDB向量搜索、Ollama大型语言模型（LLM）智能以及网页搜索功能，能够从您的知识库中提供准确且上下文感知的响应。

✨ 特点

🤖 智能查询路由 - 自动将查询路由到最优搜索策略
🔍 语义搜索 - 基于ChromaDB的向量搜索，使用mxbai-embed-large嵌入模型
💡 大语言模型意图分析 - 集成Ollama以实现查询理解和关键词提取
🌐 网络搜索备用方案 - 当 vault 无结果时，无缝回退到 Serper.dev
📊 结构化日志记录 - 基于环境的日志记录，包含调试、信息、警告、错误级别
🛡️ 安全加固 - 输入净化、注入防护和验证
🧪 经过全面测试 - 27项测试，涵盖导入、路由逻辑和安全性
📦 可通过 pip 安装 - 带有 pyproject.toml 的标准 Python 包

🏗️ 建筑

QueryMind 实现了一个 多智能体架构 带有智能路由功能：

User Query → Router → [ Fast Search Agent   ] → Results
                      [ Deep Research Agent ]
                      [ Web Search (fallback) ]

代理类型

快速搜索代理 - 对简单查询进行直接关键词匹配（\10个词 → 深入研究

疑问词“如何”、“为何”、“什么”、“解释” → 深度研究
逻辑运算符“和”、“或”、“非” → 深入研究
默认简单关键词 → 快速搜索

🚀 快速入门

先决条件

系统要求：

Python 3.9 或更高版本
8GB+ 运行内存（建议16GB以获得更佳性能）
（可选）使用NVIDIA GPU以加快嵌入速度

所需服务：

Ollama（注：这是一个专有名词，通常指一个特定的软件或项目名称，在中文中直接音译，不改变其原有含义） - 本地LLM推理（mistral:7b或类似模型）
ChromaDB（注：这可能是一个特定数据库或系统的名称，直接翻译为“色彩数据库”可能不准确，具体翻译需根据上下文或该系统的实际功能来确定，但在此仅提供字面翻译） - 用于语义搜索的向量数据库
Redis - 查询缓存（可选但推荐）

步骤1：安装Ollama

Ollama为查询分析提供本地大型语言模型（LLM）推理服务。

macOS / Linux：

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull the mistral model (7B parameters, ~4GB)
ollama pull mistral:7b

# Verify installation
ollama list

Windows：

从 https://ollama.com/download 下载安装程序
运行安装程序并按照提示操作
打开 PowerShell 并运行： ollama pull mistral:7b

验证Ollama是否正在运行：

curl http://localhost:11434/api/tags
# Should return list of installed models

步骤2：安装ChromaDB

ChromaDB 提供了向量搜索功能。

选项A：作为Python包安装（推荐用于开发）

# ChromaDB will be installed automatically with QueryMind
# It runs in-process (no separate server needed)

选项B：运行ChromaDB服务器（生产环境推荐）

# Install ChromaDB server
pip install chromadb

# Run ChromaDB server
chroma run --host localhost --port 8000

# Verify server is running
curl http://localhost:8000/api/v1/heartbeat

步骤3：安装Redis（可选）

Redis 提供查询缓存以提升性能（缓存命中率为73%）。

macOS：

brew install redis
brew services start redis

Ubuntu/Debian（译文保持原样，因为已经是中文表述，但为了符合语境，可理解为“在Ubuntu和Debian系统中”或“Ubuntu和Debian”）

sudo apt update
sudo apt install redis-server
sudo systemctl start redis

Windows（系统/操作系统）

# Download from https://github.com/microsoftarchive/redis/releases
# Or use WSL2 with Ubuntu instructions above

验证 Redis：

redis-cli ping
# Should return: PONG

步骤4：安装QueryMind

# Clone the repository
git clone https://github.com/rduffyuk/querymind.git
cd querymind

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install QueryMind with all dependencies
pip install .

# Or install in development mode
pip install -e ".[dev]"

步骤5：配置环境

创建一个 .env 示例中的文件：

cp .env.example .env

编辑 .env 根据您的设置：

# Required - Path to your markdown documents
VAULT_PATH=/path/to/your/obsidian-vault

# ChromaDB settings
CHROMADB_URL=http://localhost:8000  # Or leave blank for in-process mode

# Redis settings (optional - will fall back to in-memory cache)
REDIS_URL=redis://localhost:6379

# Ollama settings
OLLAMA_API_URL=http://localhost:11434

# Optional - Web search API key (100 free queries/month)
SERPER_API_KEY=your-api-key-here

# Logging
LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

步骤6：验证安装

运行测试套件以验证一切是否正常工作：

# Run all tests
pytest tests/ -v

# Should see: 25 passed, 2 skipped

测试一个简单查询：

from querymind import auto_search

# Simple test query
result = auto_search("test query", n_results=1)
print(f"Status: {result.status}")
print(f"Agent: {result.agent_type}")

可选：获取Serper.dev API密钥

对于网页搜索的备用功能：

在 https://serper.dev 上注册
从仪表板获取您的API密钥
添加到 .env: SERPER_API_KEY=your-key-here
免费层级：每月100次查询
免费额度之后：每1,000次查询0.30美元

可选：安装 Obsidian 用于文档管理

Obsidian是一款功能强大的Markdown编辑器，非常适合用于管理QueryMind搜索的文档库。虽然不是必需的，但它提供了极佳的界面来创建和组织您的知识库。

macOS：

# Download from website
open https://obsidian.md/download

# Or install via Homebrew
brew install --cask obsidian

Linux：

# Download AppImage from website
wget https://github.com/obsidianmd/obsidian-releases/releases/download/v1.4.16/Obsidian-1.4.16.AppImage

# Make executable and run
chmod +x Obsidian-1.4.16.AppImage
./Obsidian-1.4.16.AppImage

# Or install via Snap
sudo snap install obsidian --classic

Windows：

# Download installer from website
start https://obsidian.md/download

# Or install via Chocolatey
choco install obsidian

设置您的保险库：

打开 Obsidian
创建一个新保险库或打开现有的保险库 VAULT_PATH 来自你的 .env
开始创建Markdown文档
QueryMind将自动对这些文档进行索引和搜索

故障排除

Ollama 连接失败：

# Check if Ollama is running
ollama list

# Restart Ollama
# macOS/Linux: sudo systemctl restart ollama
# Windows: Restart Ollama Desktop app

ChromaDB 错误：

# If using server mode, check if running
curl http://localhost:8000/api/v1/heartbeat

# If in-process mode, ensure adequate RAM
# ChromaDB needs ~2-4GB for mxbai-embed-large model

Redis 不可用：

# QueryMind will fall back to in-memory cache
# To use Redis, ensure it's running:
redis-cli ping

📖 使用方法

基本搜索

from querymind import auto_search

# Simple query (uses FastSearchAgent)
result = auto_search("Redis caching")
print(f"Found {result.result_count} results")
for r in result.results:
    print(f"  - {r['file']}: {r['score']:.2f}")

# Complex query (uses DeepResearchAgent)
result = auto_search("How to implement Redis caching for APIs?")
print(f"Agent: {result.agent_type}")
print(f"Time: {result.elapsed_time:.2f}s")

高级用法

from querymind.agents.router import AgentRouter

# Initialize router with custom configuration
router = AgentRouter(
    model="mistral:7b",
    enable_web_fallback=True
)

# Execute search with verbose logging
result = router.search(
    query="Explain StatefulSet vs Deployment",
    n_results=10,
    verbose=True
)

# Get routing statistics
stats = router.get_stats()
print(f"Fast searches: {stats['fast_searches']}")
print(f"Deep searches: {stats['deep_searches']}")

直接代理访问

from querymind.agents.vault_search_agent_local import VaultSearchAgentLocal
from querymind.agents.web_search_client import WebSearchClient

# Use vault search agent directly
vault_agent = VaultSearchAgentLocal(model="mistral:7b")
result = vault_agent.search("kubernetes deployment patterns")

# Use web search directly
web_client = WebSearchClient(api_key="your-key")
results = web_client.search_sync("latest FastAPI best practices", n_results=5)

🧪 测试

运行测试套件：

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_router_basic.py -v

# Run with coverage
pytest tests/ --cov=querymind --cov-report=html

测试覆盖率：

✅ 总共27项测试
✅ 25人通过（92.6%）
⏭️ 跳过2个（可选依赖项）

测试套件

test_imports_work.py 翻译为中文是：“测试导入功能正常.py” 或者更简洁地 “测试导入工作.py” - 验证所有模块是否可以导入
test_router_basic.py 翻译为中文是：“测试路由器基础.py” 或者更简洁地表达为 “路由器基础测试脚本.py” - 验证查询路由逻辑和启发式方法
test_security_validation.py 翻译为中文是：“测试安全验证.py” - 测试输入数据净化和注入防护

🛠️ 开发

设置开发环境

# Clone repository
git clone https://github.com/rduffyuk/querymind.git
cd querymind

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

代码质量

# Format code
black querymind/ tests/

# Lint code
ruff querymind/ tests/

📋 项目结构

querymind/
├── querymind/
│   ├── __init__.py           # Package initialization
│   ├── core/                 # Core functionality
│   │   ├── __init__.py
│   │   ├── config.py         # Configuration management
│   │   ├── logging_config.py # Structured logging (NEW)
│   │   ├── embeddings.py     # ChromaDB embeddings
│   │   ├── cache.py          # Query caching (Redis)
│   │   └── conversation_memory.py  # Conversation stub (NEW)
│   ├── agents/               # Multi-agent system
│   │   ├── __init__.py
│   │   ├── base_agent.py     # Abstract base agent
│   │   ├── fast_search_agent.py    # Quick keyword search
│   │   ├── deep_research_agent.py  # LLM-powered search
│   │   ├── vault_search_agent_local.py  # Ollama integration (NEW)
│   │   ├── web_search_client.py    # Web search fallback (NEW)
│   │   └── router.py         # Intelligent routing
│   └── mcp/                  # Model Context Protocol
│       └── server.py         # FastMCP server
├── tests/                    # Test suite (NEW)
│   ├── __init__.py
│   ├── test_imports_work.py  # Import verification
│   ├── test_router_basic.py  # Routing logic tests
│   └── test_security_validation.py  # Security tests
├── pyproject.toml            # Package configuration (NEW)
├── requirements.txt          # Dependencies
├── .env.example              # Environment template
├── .gitignore                # Git ignore rules
├── LICENSE.txt               # MIT License
└── README.md                 # This file

⚙️ 配置

QueryMind 使用环境变量进行配置。请参阅 .env.example 对于所有可用选项：

核心设置

变量	描述	默认值
`VAULT_PATH`	你的Markdown文档的路径	`/vault`
`CHROMADB_URL`	ChromaDB HTTP 端点	`http://localhost:8000`
`REDIS_URL`	Redis 缓存终端节点	`redis://localhost:6379`
`OLLAMA_API_URL`	Ollama LLM 端点	`http://localhost:11434`
`LOG_LEVEL`	日志级别（DEBUG/INFO/WARNING/ERROR）	`INFO`

可选功能

变量	描述	默认值
`SERPER_API_KEY`	Serper.dev 网络搜索API密钥	无
`DISABLE_WEB_SEARCH`	禁用网页回退	`false`

🤝 贡献

欢迎投稿！请遵循以下指南：

为仓库创建分支（或“克隆仓库”）
创建一个特性分支（git checkout -b feature/amazing-feature）
做出你的更改
运行测试（pytest tests/)
提交您的更改（git commit -m 'Add amazing feature')
推送至分支（git push origin feature/amazing-feature)
打开一个拉取请求

编码规范

跟随 PEP 8（Python Enhancement Proposal 8，即Python增强提案8）风格指南
使用黑色用于代码格式化
为新功能添加测试
根据需要更新文档
使用结构化日志记录（而非打印语句）

🗺️ 路线图

当前版本（v0.1.0）

\[x\] 基于7种启发式方法的智能查询路由
\[x\] 快速搜索、深度研究、网络搜索代理
\[x\] 集成Ollama进行意图分析
\[x\] ChromaDB 向量搜索
\[x\] 结构化日志记录系统
\[x\] 综合测试套件（27个测试）
\[x\] 安全加固和输入验证

计划中（v0.2.0）

\[ \] 增强缓存功能，采用收集缓存技术
\[ \] 支持并发搜索的异步功能
\[ \] ChromaDB 的连接池
\[ \] 高级指标和监控
\[ \] REST API 端点
\[ \] 用于查询测试的Web用户界面

未来（v1.0.0）

\[ \] 完成对话记忆功能的实现
\[ \] 配置更改时的热重载
\[ \] Docker Compose 部署
\[ \] Kubernetes 部署指南
\[ \] 多语言支持

📝 许可证

这个项目遵循MIT许可证授权——详见 LICENSE.txt（许可证文件）文件中有详细信息。

🙏 致谢

QueryMind建立在优秀的开源项目之上：

ChromaDB（可译为“色度数据库”或根据具体语境译为更贴切的名称，如“色彩数据库”等，但直接保留“ChromaDB”作为专有名词使用也是常见做法） - 用于语义搜索的向量数据库
Ollama（注：Ollama是一个用于训练和运行大型语言模型的工具或平台，直接翻译为“奥拉玛”可能无法准确传达其技术含义，但在此按音译处理） - 本地大型语言模型推理
Serper.dev（注：这通常是一个指向某个特定网站或服务的域名，直接翻译为中文可能无法准确传达其含义，因此保留原样）网络搜索API
FastMCP - 模型上下文协议服务器

______________________________________________________________________

QueryMind（可译为“查询思维”或根据具体语境调整为更贴切的表述，如“智能查询助手”等，但直接翻译保持原意为“查询心智”） - 为您的知识库进行智能搜索

由...用心打造 ❤️ 瑞安·达菲

querymind (Rduffyuk)

快速接入

详细介绍