# 启用完整RAG功能指南

当前知识库管理功能已经可以使用，但**向量化功能被禁用**了。如果需要启用完整的RAG（检索增强生成）功能，包括语义搜索和AI问答，请按以下步骤操作。

## 当前状态

✅ **已启用的功能：**
- 文档上传（支持txt、pdf、doc、docx、md）
- 文档解析和文本提取
- 文本分块
- 文档列表查看
- 文档删除

❌ **未启用的功能：**
- 文本向量化（Embedding）
- 向量数据库存储
- 语义搜索
- AI智能问答

---

## 启用步骤

### 步骤1：安装并启动Ollama（本地AI服务）

#### 1.1 下载Ollama
访问官网下载：https://ollama.ai/download
- Windows: 下载安装包直接安装
- 安装后会自动启动服务（默认端口11434）

#### 1.2 下载模型
打开命令行，执行：
```bash
# 下载嵌入模型（用于向量化）
ollama pull nomic-embed-text

# 下载生成模型（用于AI问答）
ollama pull qwen2.5:7b
```

#### 1.3 验证Ollama是否运行
```bash
curl http://localhost:11434/api/tags
```
如果返回模型列表，说明Ollama正常运行。

---

### 步骤2：安装并启动ChromaDB（向量数据库）

#### 2.1 安装Python（如果没有）
下载Python 3.8+：https://www.python.org/downloads/

#### 2.2 安装ChromaDB
```bash
pip install chromadb
```

#### 2.3 启动ChromaDB服务
```bash
# 方式1：直接启动（前台运行）
chroma run --host localhost --port 8000

# 方式2：后台运行（Windows）
start /B chroma run --host localhost --port 8000
```

#### 2.4 验证ChromaDB是否运行
访问：http://localhost:8000/api/v1/heartbeat
如果返回心跳信息，说明ChromaDB正常运行。

---

### 步骤3：修改代码启用向量化

#### 3.1 打开文件
`ry-xinli-system/src/main/java/com/ddnai/system/rag/service/KnowledgeService.java`

#### 3.2 找到第98-115行左右的代码
```java
// 5. 向量化 - 添加超时和异常处理
// 暂时跳过向量化，避免超时问题
List<float[]> embeddings = null;
boolean vectorizationSuccess = false;

// TODO: 启用向量化需要先启动AI服务（Ollama或OpenAI）
log.info("Vectorization is currently disabled to avoid timeout issues");
log.info("Document will be saved without vector embeddings");

/* 取消注释以启用向量化
try {
    embeddings = embeddingService.embedBatch(chunks);
    log.info("Generated {} embeddings", embeddings.size());
    vectorizationSuccess = true;
} catch (Exception e) {
    log.warn("Failed to generate embeddings: {}", e.getMessage());
}
*/
```

#### 3.3 修改为（删除注释，启用向量化）
```java
// 5. 向量化 - 添加超时和异常处理
List<float[]> embeddings = null;
boolean vectorizationSuccess = false;

try {
    embeddings = embeddingService.embedBatch(chunks);
    log.info("Generated {} embeddings", embeddings.size());
    vectorizationSuccess = true;
} catch (Exception e) {
    log.warn("Failed to generate embeddings: {}", e.getMessage());
    // 如果向量化失败，文档仍会被保存，只是不能进行语义搜索
}
```

#### 3.4 重新编译
```bash
mvn clean package -DskipTests -pl ry-xinli-system -am
```

#### 3.5 重启后端服务

---

### 步骤4：验证功能

#### 4.1 上传测试文档
在知识库管理页面上传一个txt或md文件

#### 4.2 查看后端日志
应该看到类似的日志：
```
Parsed document: 1234 characters extracted
Split document into 5 chunks
Generated 5 embeddings
Stored 5 chunks to ChromaDB
```

#### 4.3 测试语义搜索
使用搜索功能，应该能根据语义而不是关键词匹配找到相关文档

---

## 替代方案：使用OpenAI API

如果不想安装本地服务，可以使用OpenAI API：

### 1. 获取OpenAI API Key
访问：https://platform.openai.com/api-keys

### 2. 配置API Key
在`application.yml`中添加：
```yaml
rag:
  ai:
    provider: openai
    openai:
      api-key: sk-your-api-key-here
      base-url: https://api.openai.com/v1
      model: gpt-3.5-turbo
      embedding-model: text-embedding-ada-002
```

### 3. 启用向量化代码（同步骤3）

### 4. 重启服务

---

## 快速检查脚本

创建一个批处理文件`检查RAG服务.bat`：
```batch
@echo off
echo 检查Ollama服务...
curl -s http://localhost:11434/api/tags
echo.
echo.
echo 检查ChromaDB服务...
curl -s http://localhost:8000/api/v1/heartbeat
echo.
echo.
pause
```

---

## 常见问题

### Q1: Ollama启动失败
**A:** 检查端口11434是否被占用，或重启Ollama服务

### Q2: ChromaDB连接超时
**A:** 确认ChromaDB服务正在运行，检查防火墙设置

### Q3: 向量化很慢
**A:** 
- 本地Ollama：正常，第一次加载模型较慢
- OpenAI API：检查网络连接和API配额

### Q4: 不想启用向量化，只想存储文档
**A:** 保持当前配置即可，文档会被保存和解析，只是不能进行语义搜索

---

## 总结

**最简单的方案（推荐）：**
1. 安装Ollama（一键安装）
2. 下载模型（两条命令）
3. 安装ChromaDB（一条pip命令）
4. 启动ChromaDB（一条命令）
5. 修改代码取消注释（删除几行注释）
6. 重新编译重启

**总耗时：约10-20分钟**（主要是下载模型）

如有问题，查看后端日志获取详细错误信息。