python-services/Retrieve/readme.md

# Bio RAG Server

一个基于FastAPI的生物医学检索增强生成(RAG)服务，支持PubMed文献检索、Web搜索和向量数据库查询，提供智能问答和文档检索功能。

## 🚀 功能特性

- **多源数据检索**: 支持PubMed、Web搜索、个人向量数据库等多种数据源
- **智能问答**: 基于大语言模型的RAG问答，支持流式响应
- **查询重写**: 智能查询拆分和重写，提高检索精度
- **主备切换**: 支持LLM服务的主备配置，自动故障转移
- **流式响应**: 实时流式聊天响应，提升用户体验
- **国际化支持**: 支持中英文切换，包含87个国际化消息，涵盖8种消息类型
- **日志追踪**: 完整的请求追踪和日志记录
- **CORS支持**: 跨域请求支持，便于前端集成

## 🏗️ 系统架构

```
bio_rag_server/
├── bio_agent/          # AI代理相关
├── bio_requests/       # 请求模型定义
├── config/            # 配置文件
├── dto/               # 数据传输对象
├── routers/           # API路由
├── search_service/    # 搜索服务
├── service/           # 核心业务服务
├── utils/             # 工具类
└── test/              # 测试文件
```

## 📋 环境要求

- Python 3.8+
- OpenAI API 或兼容的LLM服务

## 🛠️ 安装部署

### 1. 克隆项目

```bash
git clone <repository-url>
cd bio_rag_server-1
```

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置环境

复制并修改配置文件 `config/app_config.yaml`:

```yaml

llm:
  model: gpt-4o
  api_key: your-openai-api-key
  base_url: https://api.openai.com/v1
  max_tokens: 1024
  temperature: 0.7

qa-llm:
  main:
    model: deepseek-r1
    api_key: your-main-api-key
    base_url: https://your-main-endpoint/v1
    max_tokens: 1024
    temperature: 0.7
  backup:
    model: qwen-plus-latest
    api_key: your-backup-api-key
    base_url: https://your-backup-endpoint/v1
    max_tokens: 1024
    temperature: 0.7
```

### 4. 启动服务

```bash
python main.py
```

或使用Docker:

```bash
docker build -t bio-rag-server .
docker run -p 9487:9487 bio-rag-server
```

服务将在 `http://localhost:9487` 启动。

## 📚 API 文档

### 1. 文档检索 API

**端点**: `POST /retrieve`

**请求体**:
```json
{
  "query": "cancer treatment",
  "top_k": 5,
  "search_type": "keyword",
  "is_rewrite": true,
  "data_source": ["pubmed"],
  "user_id": "user123",
  "pubmed_topk": 30
}
```

**响应**:
```json
[
  {
    "title": "Cancer Treatment Advances",
    "abstract": "Recent advances in cancer treatment...",
    "url": "https://pubmed.ncbi.nlm.nih.gov/...",
    "score": 0.95
  }
]
```

### 2. 流式聊天 API

**端点**: `POST /stream-chat`

**请求体**:
```json
{
  "query": "What are the latest treatments for breast cancer?",
  "is_web": true,
  "is_pubmed": true,
  "language": "en"  // 可选：响应语言 (zh/en)
}
```

**响应**: Server-Sent Events (SSE) 流式响应

### 3. 国际化支持

所有API接口都支持国际化，通过 `language` 参数指定响应语言：

- `zh` (默认): 中文响应
- `en`: 英文响应

**响应格式示例**:
```json
{
  "success": true,
  "data": [...],
  "message": "搜索成功",  // 或 "Search successful"
  "language": "zh"
}
```

**错误响应格式**:
```json
{
  "success": false,
  "error": {
    "code": 500,
    "message": "搜索失败",  // 或 "Search failed"
    "language": "zh",
    "details": "具体错误信息"
  }
}
```

## 🔧 配置说明

### 数据源配置

- **pubmed**: PubMed文献数据库
- **web**: Web搜索


### LLM配置

支持主备配置，当主配置失败时自动切换到备用配置：

```yaml
qa-llm:
  main:
    model: deepseek-r1
    api_key: main-api-key
    base_url: main-endpoint
  backup:
    model: qwen-plus-latest
    api_key: backup-api-key
    base_url: backup-endpoint
```

## 🧪 测试

### 基本功能测试

运行测试用例：

```bash
cd test
python client.py
```

### 国际化功能测试

```bash
# 基本国际化功能测试
python test/test_i18n.py

# Label国际化功能测试
python test/test_label_i18n.py

# 新的消息文件结构测试
python test/test_i18n_messages.py

# 运行客户端测试示例
python test/client_test.py
```

### 使用示例

```python
import requests

# 中文检索
response_zh = requests.post("http://localhost:9487/retrieve", json={
    "query": "人工智能",
    "language": "zh"
})

# 英文检索
response_en = requests.post("http://localhost:9487/retrieve", json={
    "query": "artificial intelligence",
    "language": "en"
})
```

## 📊 监控和日志

- 日志文件位置: `logs/bio_rag_YYYY-MM-DD.log`
- 请求追踪: 每个请求都有唯一的correlation_id
- 性能监控: 自动记录请求处理时间

## 🔒 安全特性

- API密钥配置化管理
- 请求日志记录
- CORS配置
- 错误处理和安全异常

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🆘 支持

如有问题或建议，请：

1. 查看 [Issues](../../issues) 页面
2. 创建新的 Issue
3. 联系项目维护者

## 🗺️ 路线图

- [ ] 支持更多数据源
- [ ] 增加用户认证和权限管理
- [ ] 优化向量搜索性能
- [ ] 添加更多LLM模型支持
- [ ] 实现缓存机制
- [ ] 增加API限流功能

---

**注意**: 请确保在使用前正确配置所有必要的API密钥和服务端点。