base_rag/README.md

163 lines
4.1 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# BaseRAG 系统功能总结
## 概述
BaseRAG 是一个灵活的检索增强生成RAG框架支持多种嵌入模型和重排策略专注于本地部署和HuggingFace生态系统。
## 🎯 核心特性
### 1. 多种嵌入模型支持
- **本地HuggingFace模型**: 支持模型名称和本地路径两种方式
- **本地API接口**: 兼容OpenAI API格式的本地嵌入服务
- **自动回退机制**: API不可用时自动切换到本地模型
### 2. 文档重排功能
- **相似度重排**: 基于余弦相似度,无额外依赖
- **CrossEncoder重排**: 专业重排模型,效果优秀
- **BGE重排**: 中文支持良好的重排模型
### 3. 向量存储
- **Chroma数据库**: 自动持久化,支持多集合管理
- **线程安全**: 模型缓存和并发访问保护
## 🔧 配置示例
### 基础配置
```python
from base_rag import BaseRAG
class MyRAG(BaseRAG):
def ingest(self, documents):
self.vector_store.add_texts(documents)
def query(self, question, k=3):
return self.similarity_search_with_rerank(question, k=k)
# 配置
embedding_config = {
"type": "local",
"model_name": "sentence-transformers/all-MiniLM-L6-v2"
}
rerank_config = {
"enabled": True,
"method": "similarity",
"top_k": 3
}
rag = MyRAG(
embedding_config=embedding_config,
rerank_config=rerank_config
)
```
### 本地API配置
```python
embedding_config = {
"type": "api",
"api_url": "http://localhost:8080",
"model": "text-embedding-model"
}
```
### 本地模型路径配置
```python
embedding_config = {
"type": "local",
"model_path": "/path/to/your/model"
}
```
## 📁 项目结构
```
base_rag/
├── src/
│ └── base_rag/
│ ├── __init__.py # 包入口
│ └── core.py # 核心BaseRAG类
├── examples/
│ ├── quick_start.py # 快速开始示例
│ ├── rerank_demo.py # 重排功能演示
│ └── local_api_demo.py # 本地API配置示例
├── requirements.txt # 依赖列表
├── pyproject.toml # 包配置
├── RERANK_GUIDE.md # 重排功能详细说明
└── README.md # 项目说明
```
## 🚀 快速开始
1. **安装依赖**
```bash
pip install -r requirements.txt
```
2. **运行示例**
```bash
# 基础功能演示
python examples/quick_start.py
# 重排功能演示
python examples/rerank_demo.py
# 本地API配置演示
python examples/local_api_demo.py
```
## 📦 可选依赖
```bash
# 本地API接口支持
pip install langchain-openai
# BGE重排支持
pip install FlagEmbedding
```
## 🔍 API参考
### 核心方法
- `similarity_search(query, k)`: 基础相似性搜索
- `similarity_search_with_rerank(query, k)`: 带重排的搜索
- `load_and_split_documents(file_path)`: 文档加载和分割
- `add_documents_to_vector_store(documents)`: 添加文档到向量库
### 抽象方法(需实现)
- `ingest(*args, **kwargs)`: 文档导入逻辑
- `query(question)`: 问答逻辑
## 💡 最佳实践
1. **开发阶段**: 使用本地模型,快速原型验证
2. **生产环境**:
- 小规模: 本地模型 + 相似度重排
- 大规模: 本地API + CrossEncoder/BGE重排
3. **模型选择**: 根据语言和领域需求选择合适的嵌入模型
4. **重排策略**: 在实际数据上测试不同重排方法的效果
## 🛠️ 技术特点
- **线程安全**: 支持并发访问和模型缓存
- **错误处理**: 完善的异常处理和回退机制
- **灵活配置**: 支持多种配置方式和自定义参数
- **易于扩展**: 抽象设计,便于子类实现特定业务逻辑
## 📋 注意事项
1. 首次运行会下载模型,需要网络连接
2. 重排功能会增加查询延迟,但提高结果质量
3. 不同模型对硬件要求不同,请根据实际情况选择
4. 建议在生产环境前进行充分测试
## 🔄 版本信息
- **当前版本**: 0.1.0
- **Python要求**: >= 3.8
- **主要依赖**: langchain, chromadb, sentence-transformers
---
更多详细信息请参考:
- [重排功能详细说明](RERANK_GUIDE.md)
- [示例代码](examples/)
- [配置文件](pyproject.toml)