# ElasticRAG
ElasticRAG 是一个基于 Elasticsearch 的 RAG（Retrieval-Augmented Generation）系统，充分利用 Elasticsearch 的 ingest pipeline 功能来处理整个 RAG 工作流。
## 特性
- 🔍 基于 Elasticsearch 的向量搜索和文本搜索
- 🛠️ 使用 ingest pipeline 进行文档处理和向量化
- 👥 多用户支持和认证
- 🧠 多模型支持（OpenAI、HuggingFace 等）
- 📚 知识库（Collection）管理
- 🔄 混合搜索和 RRF（Reciprocal Rank Fusion）算法
- 📄 支持多种文档格式的文本分割
- ⚙️ 支持环境变量配置和命令行参数
- 🌐 可选的 Web 管理界面
- ✨ **新增**: 通过知识图谱和术语库进行增强检索
## 增强检索：结合知识图谱与术语库
ElasticRAG 支持通过集成知识图谱实体和术语库来增强用户查询，从而实现更高级的检索策略。这种混合方法结合了词法搜索、语义搜索和结构化知识，以获得更准确、更相关的结果。
### 工作原理
`Collection` 类中的 `query` 方法可以通过以下可选参数进行增强：
- `k_hop_entities`: 一个列表的列表，表示从用户查询中提取的实体的 k-hop 邻居。例如：`[['实体_A1', '实体_A2'], ['实体_B1']]`，其中第一个列表包含 1-hop 邻居，第二个列表包含 2-hop 邻居。
- `terminology`: 与查询相关的术语或同义词列表。
这些参数用于构建一个增强查询，该查询通过两种方式运作：
1. **文本搜索增强**:
* **术语库**: 使用 `match_phrase_prefix` 查询查找包含相关术语的文档。这对于同义词和技术术语非常有用。
* **实体**: 使用 `terms` 查询匹配其文本块包含所提供 k-hop 实体的文档。相关性得分（`boost`）会随着跳数的增加而衰减，从而给予更近的实体更高的权重。
2. **向量搜索增强**:
* 术语和实体与原始查询文本一起被格式化为一个结构化的提示（Prompt）。
* 这个增强的提示随后被转换为用于 KNN 搜索的嵌入向量。这丰富了查询的语义上下文，从而实现更好的相似度匹配。
### 灵活的权重配置
术语和实体对文本搜索得分的影响可以通过 `query` 方法中的 `boost_config` 参数进行自定义。该字典可以包含：
- `terminology_boost`: 术语匹配的权重（默认值：`0.6`）。
- `entity_base_boost`: 1-hop 实体匹配的基础权重（默认值：`0.4`）。
- `entity_decay_factor`: 后续跳数的衰减因子（默认值：`0.6`）。
### 数据准备
要利用基于实体的检索，您必须在数据摄入过程中从文档中提取实体，并将它们存储在每个文本块的 `metadata.entities` 字段中。这通常需要在调用 `collection.add()` 之前使用命名实体识别（NER）模型来完成。
## 安装
### 基础安装
仅安装核心功能（CLI 命令行工具）：
```bash
uv add elasticrag
```
### 完整安装
包含 Web 管理界面：
```bash
uv add 'elasticrag[web]'
```
### 开发安装
包含开发工具：
```bash
uv add 'elasticrag[dev]'
```
### 全部安装
包含所有功能：
```bash
uv add 'elasticrag[all]'
```
### 从源码安装
```bash
git clone <repository-url>
cd elasticrag
uv sync
# 或安装包含 web 界面
uv sync --extra web
```
## 配置
### 环境变量配置
创建 `.env` 文件（从 `.env.example` 复制）：
```bash
cp .env.example .env
```
编辑 `.env` 文件：
```bash
# Elasticsearch Configuration
ELASTICSEARCH_HOST=http://localhost:9200
# Authentication
ELASTICRAG_USERNAME=your_username
ELASTICRAG_API_KEY=your_api_key
# Text Embedding Service
TEXT_EMBEDDING_URL=http://your-embedding-service:8080/embed
TEXT_EMBEDDING_API_KEY=your_embedding_api_key
```
### 命令行参数
你也可以通过命令行参数覆盖环境变量：
```bash
elasticrag --host localhost:9200 -u admin -k secret setup
```
## 快速开始
### 1. 初始化系统
```bash
elasticrag setup
```
### 2. 启动 Web 管理界面（可选）
⚠️ **注意**: Web 界面需要额外安装 gradio 依赖：
```bash
# 安装 web 依赖
uv add 'elasticrag[web]'
# 启动 web 界面
elasticrag server --port 7860
```
然后访问 http://localhost:7860 进入管理界面。
默认管理员账户：
- 用户名: admin
- 密码: admin123
### 3. 使用命令行工具
```bash
# 列出可用模型
elasticrag list-models
# 添加文档
elasticrag add document.pdf -c my_collection -m my_model
# 搜索文档
elasticrag search "your query" -c my_collection -m my_model -s 10
```
你也可以在搜索时加入知识图谱和术语库参数（注意：CLI当前不支持复杂数据结构，此功能主要通过API使用）：
```python
# API 调用示例
results = await collection.query(
query_text="什么是机器学习？",
terminology=["AI", "人工智能"],
k_hop_entities=[
["深度学习", "神经网络"], # 1-hop
["TensorFlow", "PyTorch"] # 2-hop
],
boost_config={
"terminology_boost": 0.7,
"entity_base_boost": 0.5,
"entity_decay_factor": 0.5
}
)
```
## CLI 命令参考
### 全局选项
- `--host`: Elasticsearch 主机地址
- `-u, --username`: 用户名
- `-k, --api-key`: API 密钥
- `-v, --verbose`: 启用详细日志
### 命令
- `setup`: 初始化系统
- `server`: 启动 Gradio Web 管理界面 **（需要安装 web 依赖）**
- `list-models`: 列出可用模型
- `list-users`: 列出所有用户
- `list-collections`: 列出所有集合
- `list-documents [collection] [model]`: 列出文档
- `add <file_path> [-c collection] [-m model]`: 添加文档
- `search <query> [-c collection] [-m model] [-s size]`: 搜索文档
#### server 命令选项
⚠️ **注意**: server 命令需要安装额外依赖：
```bash
uv add 'elasticrag[web]'
```
然后可以使用：
```bash
elasticrag server [选项]
选项:
--port PORT Web界面端口 (默认: 7860)
--host HOST Web界面主机 (默认: 0.0.0.0)
--share 通过 Gradio 创建公共链接
--admin-username USER 管理员用户名
--admin-password PASS 管理员密码
```
## 依赖说明
### 核心依赖
- `elasticsearch>=8.0.0`: Elasticsearch 客户端
- `python-dotenv>=1.0.0`: 环境变量管理
- `aiohttp>=3.10.11`: 异步 HTTP 客户端
### 可选依赖
#### Web 界面 (`elasticrag[web]`)
- `gradio>=4.0.0`: Web 界面框架
- `pandas>=1.3.0`: 数据处理
#### 开发工具 (`elasticrag[dev]`)
- `pytest>=7.0.0`: 测试框架
- `pytest-asyncio>=0.21.0`: 异步测试支持
- `black>=23.0.0`: 代码格式化
- `isort>=5.12.0`: 导入排序
## Web 管理界面
### 安装 Web 依赖
```bash
uv add 'elasticrag[web]'
```
### 管理员功能
使用管理员账户登录后可以：
- **用户管理**: 查看、添加、删除用户
- **模型管理**: 查看、添加模型配置
- **系统监控**: 查看系统状态和资源使用
### 用户功能
使用普通用户账户登录后可以：
- **集合管理**: 查看自己的文档集合
- **文档管理**: 添加、删除、查看文档
- **搜索调试**: 在集合中搜索文档并查看结果
### 环境变量配置
Web 界面相关的环境变量：
```bash
# 管理员账户配置
ELASTICRAG_ADMIN_USERNAME=admin
ELASTICRAG_ADMIN_PASSWORD=admin123
```
## API 使用
```python
from elasticrag import Client
# 创建客户端
client = Client('http://localhost:9200')
# 认证用户
user = client.authenticate('username', 'api_key')
# 获取集合
collection = client.get_collection('my_collection', 'my_model')
# 添加文档
collection.add('doc_id', 'Document Name', text_content='Your content here')
# 搜索
results = await collection.query('your query')
# 使用知识图谱和术语库进行增强搜索
kg_results = await collection.query(
query_text='your query',
terminology=['term1', 'term2'],
k_hop_entities=[['entity1'], ['entity2']],
boost_config={'terminology_boost': 0.8}
)
```
## 开发
```bash
# 安装开发依赖
uv sync --extra dev
# 安装所有依赖（包括 web）
uv sync --extra all
# 运行测试
uv run pytest
# 运行异步测试（使用 anyio）
uv run pytest tests/ -v
# 代码格式化
uv run black .
uv run isort .
```
### 测试框架
项目使用 `pytest-asyncio` 进行异步测试。这允许 `pytest` 直接运行 `async def` 测试函数。
- **事件循环管理**: `pytest-asyncio` 为每个测试函数创建并管理独立的事件循环，确保测试之间的隔离。
- **异步 Fixtures**: 支持 `async def` fixtures，可以方便地设置和清理异步资源。
测试命令：
```bash
# 运行所有测试
uv run pytest tests/ -v
# 运行特定的异步测试
uv run pytest tests/test_enhanced_query.py::TestQueryExecution::test_query_basic -v
# 启用详细输出
uv run pytest tests/ -v -s
```
## 许可证
MIT License
Raw data
{
"_id": null,
"home_page": null,
"name": "elasticrag",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "elasticsearch, embedding, nlp, rag, vector-search",
"author": null,
"author_email": "Lloyd Zhou <lloydzhou@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/e5/09/9e817338912f2843df5e99e49df86588c04a8b1d85763a14a2ae8014648e/elasticrag-0.3.2.tar.gz",
"platform": null,
"description": "# ElasticRAG\n\nElasticRAG \u662f\u4e00\u4e2a\u57fa\u4e8e Elasticsearch \u7684 RAG\uff08Retrieval-Augmented Generation\uff09\u7cfb\u7edf\uff0c\u5145\u5206\u5229\u7528 Elasticsearch \u7684 ingest pipeline \u529f\u80fd\u6765\u5904\u7406\u6574\u4e2a RAG \u5de5\u4f5c\u6d41\u3002\n\n## \u7279\u6027\n\n- \ud83d\udd0d \u57fa\u4e8e Elasticsearch \u7684\u5411\u91cf\u641c\u7d22\u548c\u6587\u672c\u641c\u7d22\n- \ud83d\udee0\ufe0f \u4f7f\u7528 ingest pipeline \u8fdb\u884c\u6587\u6863\u5904\u7406\u548c\u5411\u91cf\u5316\n- \ud83d\udc65 \u591a\u7528\u6237\u652f\u6301\u548c\u8ba4\u8bc1\n- \ud83e\udde0 \u591a\u6a21\u578b\u652f\u6301\uff08OpenAI\u3001HuggingFace \u7b49\uff09\n- \ud83d\udcda \u77e5\u8bc6\u5e93\uff08Collection\uff09\u7ba1\u7406\n- \ud83d\udd04 \u6df7\u5408\u641c\u7d22\u548c RRF\uff08Reciprocal Rank Fusion\uff09\u7b97\u6cd5\n- \ud83d\udcc4 \u652f\u6301\u591a\u79cd\u6587\u6863\u683c\u5f0f\u7684\u6587\u672c\u5206\u5272\n- \u2699\ufe0f \u652f\u6301\u73af\u5883\u53d8\u91cf\u914d\u7f6e\u548c\u547d\u4ee4\u884c\u53c2\u6570\n- \ud83c\udf10 \u53ef\u9009\u7684 Web \u7ba1\u7406\u754c\u9762\n- \u2728 **\u65b0\u589e**: \u901a\u8fc7\u77e5\u8bc6\u56fe\u8c31\u548c\u672f\u8bed\u5e93\u8fdb\u884c\u589e\u5f3a\u68c0\u7d22\n\n## \u589e\u5f3a\u68c0\u7d22\uff1a\u7ed3\u5408\u77e5\u8bc6\u56fe\u8c31\u4e0e\u672f\u8bed\u5e93\n\nElasticRAG \u652f\u6301\u901a\u8fc7\u96c6\u6210\u77e5\u8bc6\u56fe\u8c31\u5b9e\u4f53\u548c\u672f\u8bed\u5e93\u6765\u589e\u5f3a\u7528\u6237\u67e5\u8be2\uff0c\u4ece\u800c\u5b9e\u73b0\u66f4\u9ad8\u7ea7\u7684\u68c0\u7d22\u7b56\u7565\u3002\u8fd9\u79cd\u6df7\u5408\u65b9\u6cd5\u7ed3\u5408\u4e86\u8bcd\u6cd5\u641c\u7d22\u3001\u8bed\u4e49\u641c\u7d22\u548c\u7ed3\u6784\u5316\u77e5\u8bc6\uff0c\u4ee5\u83b7\u5f97\u66f4\u51c6\u786e\u3001\u66f4\u76f8\u5173\u7684\u7ed3\u679c\u3002\n\n### \u5de5\u4f5c\u539f\u7406\n\n`Collection` \u7c7b\u4e2d\u7684 `query` \u65b9\u6cd5\u53ef\u4ee5\u901a\u8fc7\u4ee5\u4e0b\u53ef\u9009\u53c2\u6570\u8fdb\u884c\u589e\u5f3a\uff1a\n\n- `k_hop_entities`: \u4e00\u4e2a\u5217\u8868\u7684\u5217\u8868\uff0c\u8868\u793a\u4ece\u7528\u6237\u67e5\u8be2\u4e2d\u63d0\u53d6\u7684\u5b9e\u4f53\u7684 k-hop \u90bb\u5c45\u3002\u4f8b\u5982\uff1a`[['\u5b9e\u4f53_A1', '\u5b9e\u4f53_A2'], ['\u5b9e\u4f53_B1']]`\uff0c\u5176\u4e2d\u7b2c\u4e00\u4e2a\u5217\u8868\u5305\u542b 1-hop \u90bb\u5c45\uff0c\u7b2c\u4e8c\u4e2a\u5217\u8868\u5305\u542b 2-hop \u90bb\u5c45\u3002\n- `terminology`: \u4e0e\u67e5\u8be2\u76f8\u5173\u7684\u672f\u8bed\u6216\u540c\u4e49\u8bcd\u5217\u8868\u3002\n\n\u8fd9\u4e9b\u53c2\u6570\u7528\u4e8e\u6784\u5efa\u4e00\u4e2a\u589e\u5f3a\u67e5\u8be2\uff0c\u8be5\u67e5\u8be2\u901a\u8fc7\u4e24\u79cd\u65b9\u5f0f\u8fd0\u4f5c\uff1a\n\n1. **\u6587\u672c\u641c\u7d22\u589e\u5f3a**:\n * **\u672f\u8bed\u5e93**: \u4f7f\u7528 `match_phrase_prefix` \u67e5\u8be2\u67e5\u627e\u5305\u542b\u76f8\u5173\u672f\u8bed\u7684\u6587\u6863\u3002\u8fd9\u5bf9\u4e8e\u540c\u4e49\u8bcd\u548c\u6280\u672f\u672f\u8bed\u975e\u5e38\u6709\u7528\u3002\n * **\u5b9e\u4f53**: \u4f7f\u7528 `terms` \u67e5\u8be2\u5339\u914d\u5176\u6587\u672c\u5757\u5305\u542b\u6240\u63d0\u4f9b k-hop \u5b9e\u4f53\u7684\u6587\u6863\u3002\u76f8\u5173\u6027\u5f97\u5206\uff08`boost`\uff09\u4f1a\u968f\u7740\u8df3\u6570\u7684\u589e\u52a0\u800c\u8870\u51cf\uff0c\u4ece\u800c\u7ed9\u4e88\u66f4\u8fd1\u7684\u5b9e\u4f53\u66f4\u9ad8\u7684\u6743\u91cd\u3002\n\n2. **\u5411\u91cf\u641c\u7d22\u589e\u5f3a**:\n * \u672f\u8bed\u548c\u5b9e\u4f53\u4e0e\u539f\u59cb\u67e5\u8be2\u6587\u672c\u4e00\u8d77\u88ab\u683c\u5f0f\u5316\u4e3a\u4e00\u4e2a\u7ed3\u6784\u5316\u7684\u63d0\u793a\uff08Prompt\uff09\u3002\n * \u8fd9\u4e2a\u589e\u5f3a\u7684\u63d0\u793a\u968f\u540e\u88ab\u8f6c\u6362\u4e3a\u7528\u4e8e KNN \u641c\u7d22\u7684\u5d4c\u5165\u5411\u91cf\u3002\u8fd9\u4e30\u5bcc\u4e86\u67e5\u8be2\u7684\u8bed\u4e49\u4e0a\u4e0b\u6587\uff0c\u4ece\u800c\u5b9e\u73b0\u66f4\u597d\u7684\u76f8\u4f3c\u5ea6\u5339\u914d\u3002\n\n### \u7075\u6d3b\u7684\u6743\u91cd\u914d\u7f6e\n\n\u672f\u8bed\u548c\u5b9e\u4f53\u5bf9\u6587\u672c\u641c\u7d22\u5f97\u5206\u7684\u5f71\u54cd\u53ef\u4ee5\u901a\u8fc7 `query` \u65b9\u6cd5\u4e2d\u7684 `boost_config` \u53c2\u6570\u8fdb\u884c\u81ea\u5b9a\u4e49\u3002\u8be5\u5b57\u5178\u53ef\u4ee5\u5305\u542b\uff1a\n\n- `terminology_boost`: \u672f\u8bed\u5339\u914d\u7684\u6743\u91cd\uff08\u9ed8\u8ba4\u503c\uff1a`0.6`\uff09\u3002\n- `entity_base_boost`: 1-hop \u5b9e\u4f53\u5339\u914d\u7684\u57fa\u7840\u6743\u91cd\uff08\u9ed8\u8ba4\u503c\uff1a`0.4`\uff09\u3002\n- `entity_decay_factor`: \u540e\u7eed\u8df3\u6570\u7684\u8870\u51cf\u56e0\u5b50\uff08\u9ed8\u8ba4\u503c\uff1a`0.6`\uff09\u3002\n\n### \u6570\u636e\u51c6\u5907\n\n\u8981\u5229\u7528\u57fa\u4e8e\u5b9e\u4f53\u7684\u68c0\u7d22\uff0c\u60a8\u5fc5\u987b\u5728\u6570\u636e\u6444\u5165\u8fc7\u7a0b\u4e2d\u4ece\u6587\u6863\u4e2d\u63d0\u53d6\u5b9e\u4f53\uff0c\u5e76\u5c06\u5b83\u4eec\u5b58\u50a8\u5728\u6bcf\u4e2a\u6587\u672c\u5757\u7684 `metadata.entities` \u5b57\u6bb5\u4e2d\u3002\u8fd9\u901a\u5e38\u9700\u8981\u5728\u8c03\u7528 `collection.add()` \u4e4b\u524d\u4f7f\u7528\u547d\u540d\u5b9e\u4f53\u8bc6\u522b\uff08NER\uff09\u6a21\u578b\u6765\u5b8c\u6210\u3002\n\n## \u5b89\u88c5\n\n### \u57fa\u7840\u5b89\u88c5\n\n\u4ec5\u5b89\u88c5\u6838\u5fc3\u529f\u80fd\uff08CLI \u547d\u4ee4\u884c\u5de5\u5177\uff09\uff1a\n\n```bash\nuv add elasticrag\n```\n\n### \u5b8c\u6574\u5b89\u88c5\n\n\u5305\u542b Web \u7ba1\u7406\u754c\u9762\uff1a\n\n```bash\nuv add 'elasticrag[web]'\n```\n\n### \u5f00\u53d1\u5b89\u88c5\n\n\u5305\u542b\u5f00\u53d1\u5de5\u5177\uff1a\n\n```bash\nuv add 'elasticrag[dev]'\n```\n\n### \u5168\u90e8\u5b89\u88c5\n\n\u5305\u542b\u6240\u6709\u529f\u80fd\uff1a\n\n```bash\nuv add 'elasticrag[all]'\n```\n\n### \u4ece\u6e90\u7801\u5b89\u88c5\n\n```bash\ngit clone <repository-url>\ncd elasticrag\nuv sync\n# \u6216\u5b89\u88c5\u5305\u542b web \u754c\u9762\nuv sync --extra web\n```\n\n## \u914d\u7f6e\n\n### \u73af\u5883\u53d8\u91cf\u914d\u7f6e\n\n\u521b\u5efa `.env` \u6587\u4ef6\uff08\u4ece `.env.example` \u590d\u5236\uff09\uff1a\n\n```bash\ncp .env.example .env\n```\n\n\u7f16\u8f91 `.env` \u6587\u4ef6\uff1a\n\n```bash\n# Elasticsearch Configuration\nELASTICSEARCH_HOST=http://localhost:9200\n\n# Authentication\nELASTICRAG_USERNAME=your_username\nELASTICRAG_API_KEY=your_api_key\n\n# Text Embedding Service\nTEXT_EMBEDDING_URL=http://your-embedding-service:8080/embed\nTEXT_EMBEDDING_API_KEY=your_embedding_api_key\n```\n\n### \u547d\u4ee4\u884c\u53c2\u6570\n\n\u4f60\u4e5f\u53ef\u4ee5\u901a\u8fc7\u547d\u4ee4\u884c\u53c2\u6570\u8986\u76d6\u73af\u5883\u53d8\u91cf\uff1a\n\n```bash\nelasticrag --host localhost:9200 -u admin -k secret setup\n```\n\n## \u5feb\u901f\u5f00\u59cb\n\n### 1. \u521d\u59cb\u5316\u7cfb\u7edf\n\n```bash\nelasticrag setup\n```\n\n### 2. \u542f\u52a8 Web \u7ba1\u7406\u754c\u9762\uff08\u53ef\u9009\uff09\n\n\u26a0\ufe0f **\u6ce8\u610f**: Web \u754c\u9762\u9700\u8981\u989d\u5916\u5b89\u88c5 gradio \u4f9d\u8d56\uff1a\n\n```bash\n# \u5b89\u88c5 web \u4f9d\u8d56\nuv add 'elasticrag[web]'\n\n# \u542f\u52a8 web \u754c\u9762\nelasticrag server --port 7860\n```\n\n\u7136\u540e\u8bbf\u95ee http://localhost:7860 \u8fdb\u5165\u7ba1\u7406\u754c\u9762\u3002\n\n\u9ed8\u8ba4\u7ba1\u7406\u5458\u8d26\u6237\uff1a\n- \u7528\u6237\u540d: admin\n- \u5bc6\u7801: admin123\n\n### 3. \u4f7f\u7528\u547d\u4ee4\u884c\u5de5\u5177\n\n```bash\n# \u5217\u51fa\u53ef\u7528\u6a21\u578b\nelasticrag list-models\n\n# \u6dfb\u52a0\u6587\u6863\nelasticrag add document.pdf -c my_collection -m my_model\n\n# \u641c\u7d22\u6587\u6863\nelasticrag search \"your query\" -c my_collection -m my_model -s 10\n```\n\n\u4f60\u4e5f\u53ef\u4ee5\u5728\u641c\u7d22\u65f6\u52a0\u5165\u77e5\u8bc6\u56fe\u8c31\u548c\u672f\u8bed\u5e93\u53c2\u6570\uff08\u6ce8\u610f\uff1aCLI\u5f53\u524d\u4e0d\u652f\u6301\u590d\u6742\u6570\u636e\u7ed3\u6784\uff0c\u6b64\u529f\u80fd\u4e3b\u8981\u901a\u8fc7API\u4f7f\u7528\uff09\uff1a\n\n```python\n# API \u8c03\u7528\u793a\u4f8b\nresults = await collection.query(\n query_text=\"\u4ec0\u4e48\u662f\u673a\u5668\u5b66\u4e60\uff1f\",\n terminology=[\"AI\", \"\u4eba\u5de5\u667a\u80fd\"],\n k_hop_entities=[\n [\"\u6df1\u5ea6\u5b66\u4e60\", \"\u795e\u7ecf\u7f51\u7edc\"], # 1-hop\n [\"TensorFlow\", \"PyTorch\"] # 2-hop\n ],\n boost_config={\n \"terminology_boost\": 0.7,\n \"entity_base_boost\": 0.5,\n \"entity_decay_factor\": 0.5\n }\n)\n```\n\n## CLI \u547d\u4ee4\u53c2\u8003\n\n### \u5168\u5c40\u9009\u9879\n\n- `--host`: Elasticsearch \u4e3b\u673a\u5730\u5740\n- `-u, --username`: \u7528\u6237\u540d\n- `-k, --api-key`: API \u5bc6\u94a5\n- `-v, --verbose`: \u542f\u7528\u8be6\u7ec6\u65e5\u5fd7\n\n### \u547d\u4ee4\n\n- `setup`: \u521d\u59cb\u5316\u7cfb\u7edf\n- `server`: \u542f\u52a8 Gradio Web \u7ba1\u7406\u754c\u9762 **\uff08\u9700\u8981\u5b89\u88c5 web \u4f9d\u8d56\uff09**\n- `list-models`: \u5217\u51fa\u53ef\u7528\u6a21\u578b\n- `list-users`: \u5217\u51fa\u6240\u6709\u7528\u6237\n- `list-collections`: \u5217\u51fa\u6240\u6709\u96c6\u5408\n- `list-documents [collection] [model]`: \u5217\u51fa\u6587\u6863\n- `add <file_path> [-c collection] [-m model]`: \u6dfb\u52a0\u6587\u6863\n- `search <query> [-c collection] [-m model] [-s size]`: \u641c\u7d22\u6587\u6863\n\n#### server \u547d\u4ee4\u9009\u9879\n\n\u26a0\ufe0f **\u6ce8\u610f**: server \u547d\u4ee4\u9700\u8981\u5b89\u88c5\u989d\u5916\u4f9d\u8d56\uff1a\n\n```bash\nuv add 'elasticrag[web]'\n```\n\n\u7136\u540e\u53ef\u4ee5\u4f7f\u7528\uff1a\n\n```bash\nelasticrag server [\u9009\u9879]\n\n\u9009\u9879:\n --port PORT Web\u754c\u9762\u7aef\u53e3 (\u9ed8\u8ba4: 7860)\n --host HOST Web\u754c\u9762\u4e3b\u673a (\u9ed8\u8ba4: 0.0.0.0)\n --share \u901a\u8fc7 Gradio \u521b\u5efa\u516c\u5171\u94fe\u63a5\n --admin-username USER \u7ba1\u7406\u5458\u7528\u6237\u540d\n --admin-password PASS \u7ba1\u7406\u5458\u5bc6\u7801\n```\n\n## \u4f9d\u8d56\u8bf4\u660e\n\n### \u6838\u5fc3\u4f9d\u8d56\n\n- `elasticsearch>=8.0.0`: Elasticsearch \u5ba2\u6237\u7aef\n- `python-dotenv>=1.0.0`: \u73af\u5883\u53d8\u91cf\u7ba1\u7406\n- `aiohttp>=3.10.11`: \u5f02\u6b65 HTTP \u5ba2\u6237\u7aef\n\n### \u53ef\u9009\u4f9d\u8d56\n\n#### Web \u754c\u9762 (`elasticrag[web]`)\n\n- `gradio>=4.0.0`: Web \u754c\u9762\u6846\u67b6\n- `pandas>=1.3.0`: \u6570\u636e\u5904\u7406\n\n#### \u5f00\u53d1\u5de5\u5177 (`elasticrag[dev]`)\n\n- `pytest>=7.0.0`: \u6d4b\u8bd5\u6846\u67b6\n- `pytest-asyncio>=0.21.0`: \u5f02\u6b65\u6d4b\u8bd5\u652f\u6301\n- `black>=23.0.0`: \u4ee3\u7801\u683c\u5f0f\u5316\n- `isort>=5.12.0`: \u5bfc\u5165\u6392\u5e8f\n\n## Web \u7ba1\u7406\u754c\u9762\n\n### \u5b89\u88c5 Web \u4f9d\u8d56\n\n```bash\nuv add 'elasticrag[web]'\n```\n\n### \u7ba1\u7406\u5458\u529f\u80fd\n\n\u4f7f\u7528\u7ba1\u7406\u5458\u8d26\u6237\u767b\u5f55\u540e\u53ef\u4ee5\uff1a\n\n- **\u7528\u6237\u7ba1\u7406**: \u67e5\u770b\u3001\u6dfb\u52a0\u3001\u5220\u9664\u7528\u6237\n- **\u6a21\u578b\u7ba1\u7406**: \u67e5\u770b\u3001\u6dfb\u52a0\u6a21\u578b\u914d\u7f6e\n- **\u7cfb\u7edf\u76d1\u63a7**: \u67e5\u770b\u7cfb\u7edf\u72b6\u6001\u548c\u8d44\u6e90\u4f7f\u7528\n\n### \u7528\u6237\u529f\u80fd\n\n\u4f7f\u7528\u666e\u901a\u7528\u6237\u8d26\u6237\u767b\u5f55\u540e\u53ef\u4ee5\uff1a\n\n- **\u96c6\u5408\u7ba1\u7406**: \u67e5\u770b\u81ea\u5df1\u7684\u6587\u6863\u96c6\u5408\n- **\u6587\u6863\u7ba1\u7406**: \u6dfb\u52a0\u3001\u5220\u9664\u3001\u67e5\u770b\u6587\u6863\n- **\u641c\u7d22\u8c03\u8bd5**: \u5728\u96c6\u5408\u4e2d\u641c\u7d22\u6587\u6863\u5e76\u67e5\u770b\u7ed3\u679c\n\n### \u73af\u5883\u53d8\u91cf\u914d\u7f6e\n\nWeb \u754c\u9762\u76f8\u5173\u7684\u73af\u5883\u53d8\u91cf\uff1a\n\n```bash\n# \u7ba1\u7406\u5458\u8d26\u6237\u914d\u7f6e\nELASTICRAG_ADMIN_USERNAME=admin\nELASTICRAG_ADMIN_PASSWORD=admin123\n```\n\n## API \u4f7f\u7528\n\n```python\nfrom elasticrag import Client\n\n# \u521b\u5efa\u5ba2\u6237\u7aef\nclient = Client('http://localhost:9200')\n\n# \u8ba4\u8bc1\u7528\u6237\nuser = client.authenticate('username', 'api_key')\n\n# \u83b7\u53d6\u96c6\u5408\ncollection = client.get_collection('my_collection', 'my_model')\n\n# \u6dfb\u52a0\u6587\u6863\ncollection.add('doc_id', 'Document Name', text_content='Your content here')\n\n# \u641c\u7d22\nresults = await collection.query('your query')\n\n# \u4f7f\u7528\u77e5\u8bc6\u56fe\u8c31\u548c\u672f\u8bed\u5e93\u8fdb\u884c\u589e\u5f3a\u641c\u7d22\nkg_results = await collection.query(\n query_text='your query',\n terminology=['term1', 'term2'],\n k_hop_entities=[['entity1'], ['entity2']],\n boost_config={'terminology_boost': 0.8}\n)\n```\n\n## \u5f00\u53d1\n\n```bash\n# \u5b89\u88c5\u5f00\u53d1\u4f9d\u8d56\nuv sync --extra dev\n\n# \u5b89\u88c5\u6240\u6709\u4f9d\u8d56\uff08\u5305\u62ec web\uff09\nuv sync --extra all\n\n# \u8fd0\u884c\u6d4b\u8bd5\nuv run pytest\n\n# \u8fd0\u884c\u5f02\u6b65\u6d4b\u8bd5\uff08\u4f7f\u7528 anyio\uff09\nuv run pytest tests/ -v\n\n# \u4ee3\u7801\u683c\u5f0f\u5316\nuv run black .\nuv run isort .\n```\n\n### \u6d4b\u8bd5\u6846\u67b6\n\n\u9879\u76ee\u4f7f\u7528 `pytest-asyncio` \u8fdb\u884c\u5f02\u6b65\u6d4b\u8bd5\u3002\u8fd9\u5141\u8bb8 `pytest` \u76f4\u63a5\u8fd0\u884c `async def` \u6d4b\u8bd5\u51fd\u6570\u3002\n\n- **\u4e8b\u4ef6\u5faa\u73af\u7ba1\u7406**: `pytest-asyncio` \u4e3a\u6bcf\u4e2a\u6d4b\u8bd5\u51fd\u6570\u521b\u5efa\u5e76\u7ba1\u7406\u72ec\u7acb\u7684\u4e8b\u4ef6\u5faa\u73af\uff0c\u786e\u4fdd\u6d4b\u8bd5\u4e4b\u95f4\u7684\u9694\u79bb\u3002\n- **\u5f02\u6b65 Fixtures**: \u652f\u6301 `async def` fixtures\uff0c\u53ef\u4ee5\u65b9\u4fbf\u5730\u8bbe\u7f6e\u548c\u6e05\u7406\u5f02\u6b65\u8d44\u6e90\u3002\n\n\u6d4b\u8bd5\u547d\u4ee4\uff1a\n\n```bash\n# \u8fd0\u884c\u6240\u6709\u6d4b\u8bd5\nuv run pytest tests/ -v\n\n# \u8fd0\u884c\u7279\u5b9a\u7684\u5f02\u6b65\u6d4b\u8bd5\nuv run pytest tests/test_enhanced_query.py::TestQueryExecution::test_query_basic -v\n\n# \u542f\u7528\u8be6\u7ec6\u8f93\u51fa\nuv run pytest tests/ -v -s\n```\n\n## \u8bb8\u53ef\u8bc1\n\nMIT License\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Elasticsearch-based RAG system with ingest pipeline processing",
"version": "0.3.2",
"project_urls": {
"Documentation": "https://github.com/lloydzhou/elasticrag#readme",
"Homepage": "https://github.com/lloydzhou/elasticrag",
"Issues": "https://github.com/lloydzhou/elasticrag/issues",
"Repository": "https://github.com/lloydzhou/elasticrag"
},
"split_keywords": [
"elasticsearch",
" embedding",
" nlp",
" rag",
" vector-search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "01473d72064d82372e57ac82520caa4f666677057b268b960c3e00be7c9569f0",
"md5": "02b88391603a2a1118377888e8cc0492",
"sha256": "28dd3fc8bcf4fc84fbc2859926188b8f74fa0deebf71fc92c9b3ad2d430cfa69"
},
"downloads": -1,
"filename": "elasticrag-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "02b88391603a2a1118377888e8cc0492",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 32947,
"upload_time": "2025-07-27T08:33:50",
"upload_time_iso_8601": "2025-07-27T08:33:50.358161Z",
"url": "https://files.pythonhosted.org/packages/01/47/3d72064d82372e57ac82520caa4f666677057b268b960c3e00be7c9569f0/elasticrag-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e5099e817338912f2843df5e99e49df86588c04a8b1d85763a14a2ae8014648e",
"md5": "b2e648240962e181469e867b5cf2f35f",
"sha256": "ce4c5995fe08e7c4b9443f03c0b72cebe258c9f72ee4f0191220eeaccfc4a94b"
},
"downloads": -1,
"filename": "elasticrag-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "b2e648240962e181469e867b5cf2f35f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 29748,
"upload_time": "2025-07-27T08:33:52",
"upload_time_iso_8601": "2025-07-27T08:33:52.041210Z",
"url": "https://files.pythonhosted.org/packages/e5/09/9e817338912f2843df5e99e49df86588c04a8b1d85763a14a2ae8014648e/elasticrag-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 08:33:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lloydzhou",
"github_project": "elasticrag#readme",
"github_not_found": true,
"lcname": "elasticrag"
}
JSON
