270 lines
5.9 KiB
Markdown
270 lines
5.9 KiB
Markdown
# RAG 知识库搭建
|
||
|
||
> 上传文档、向量化存储，构建企业级知识库问答系统。
|
||
|
||
## 🧠 什么是 RAG？
|
||
|
||
RAG（Retrieval-Augmented Generation，检索增强生成）是一种结合「知识检索」和「AI 生成」的技术：
|
||
|
||
1. **检索**：从知识库中找到相关内容
|
||
2. **增强**：将检索结果作为上下文
|
||
3. **生成**：让 AI 基于上下文生成答案
|
||
|
||
```
|
||
用户问题 → 检索相关文档 → 拼接到 Prompt → AI 生成回答
|
||
```
|
||
|
||
## 📋 适用场景
|
||
|
||
- 📄 企业内部文档问答
|
||
- 🎯 产品 FAQ 自动化
|
||
- 📚 培训资料检索
|
||
- 🔍 合同/政策查询
|
||
- 🏥 专业知识库
|
||
|
||
## 🚀 搭建步骤
|
||
|
||
### 第一步：创建知识库
|
||
|
||
```typescript
|
||
const knowledgeBase = await client.ai.createKnowledgeBase({
|
||
name: '产品使用手册',
|
||
description: '公司产品相关文档',
|
||
// 向量化模型
|
||
embeddingModel: 'text-embedding-3-small',
|
||
// 分块策略
|
||
chunking: {
|
||
type: 'recursive',
|
||
chunkSize: 1000,
|
||
chunkOverlap: 200
|
||
}
|
||
})
|
||
|
||
console.log('知识库 ID:', knowledgeBase.id)
|
||
```
|
||
|
||
### 第二步：上传文档
|
||
|
||
支持格式：PDF、Word、TXT、Markdown、HTML
|
||
|
||
```typescript
|
||
// 上传单个文件
|
||
const doc = await client.ai.uploadDocument(knowledgeBase.id, {
|
||
file: './docs/user-guide.pdf',
|
||
metadata: {
|
||
category: 'manual',
|
||
version: '2.0',
|
||
language: 'zh-CN'
|
||
}
|
||
})
|
||
|
||
console.log('文档 ID:', doc.id)
|
||
console.log('状态:', doc.status) // processing → ready
|
||
|
||
// 批量上传
|
||
const docs = await client.ai.uploadDocuments(knowledgeBase.id, [
|
||
{ file: './docs/faq.md', metadata: { category: 'faq' } },
|
||
{ file: './docs/api.md', metadata: { category: 'api' } },
|
||
{ file: './docs/tutorial.md', metadata: { category: 'tutorial' } }
|
||
])
|
||
```
|
||
|
||
### 第三步：等待处理
|
||
|
||
文档需要经过：
|
||
1. **解析**：提取文本内容
|
||
2. **分块**：按策略切分成小块
|
||
3. **向量化**：转成数学向量
|
||
|
||
```typescript
|
||
// 查询文档状态
|
||
const status = await client.ai.getDocumentStatus(doc.id)
|
||
console.log('处理状态:', status.processing_status)
|
||
console.log('块数量:', status.chunk_count)
|
||
```
|
||
|
||
### 第四步：配置检索
|
||
|
||
```typescript
|
||
await client.ai.configureRetrieval(knowledgeBase.id, {
|
||
// 检索参数
|
||
retrieval: {
|
||
topK: 5, // 返回前 5 条
|
||
scoreThreshold: 0.7, // 相似度阈值
|
||
hybridSearch: true // 混合搜索（关键词+向量）
|
||
},
|
||
// Rerank 配置
|
||
rerank: {
|
||
enabled: true,
|
||
model: 'bge-reranker'
|
||
}
|
||
})
|
||
```
|
||
|
||
### 第五步：问答
|
||
|
||
```typescript
|
||
const response = await client.ai.ask({
|
||
knowledgeBaseId: knowledgeBase.id,
|
||
question: '如何创建新项目？',
|
||
// 可选参数
|
||
options: {
|
||
maxTokens: 1000,
|
||
temperature: 0.7,
|
||
includeSources: true // 返回引用的文档片段
|
||
}
|
||
})
|
||
|
||
console.log('回答:', response.answer)
|
||
console.log('引用:', response.citations)
|
||
```
|
||
|
||
### 响应示例
|
||
|
||
```json
|
||
{
|
||
"answer": "创建新项目的步骤如下：\n1. 点击「新建项目」按钮\n2. 填写项目名称和描述\n3. 选择项目模板\n4. 点击「创建」完成",
|
||
"citations": [
|
||
{
|
||
"document_id": "doc_abc123",
|
||
"chunk_text": "点击「新建项目」按钮，进入项目创建页面...",
|
||
"score": 0.95
|
||
}
|
||
],
|
||
"model": "gpt-4",
|
||
"tokens_used": 850
|
||
}
|
||
```
|
||
|
||
## 🔧 高级配置
|
||
|
||
### 自定义分块策略
|
||
|
||
```typescript
|
||
const kb = await client.ai.createKnowledgeBase({
|
||
name: '技术文档',
|
||
chunking: {
|
||
type: 'custom',
|
||
// 按标题分块
|
||
delimiters: ['# ', '## ', '### '],
|
||
maxTokens: 500
|
||
}
|
||
})
|
||
```
|
||
|
||
### 元数据过滤
|
||
|
||
```typescript
|
||
const response = await client.ai.ask({
|
||
knowledgeBaseId: knowledgeBase.id,
|
||
question: '退款政策是什么？',
|
||
filters: {
|
||
category: 'policy',
|
||
version: '>=2.0'
|
||
}
|
||
})
|
||
```
|
||
|
||
### 多知识库查询
|
||
|
||
```typescript
|
||
const response = await client.ai.ask({
|
||
knowledgeBaseIds: ['kb-product', 'kb-faq', 'kb-manual'],
|
||
question: '这个功能如何使用？',
|
||
// 权重配置
|
||
weights: {
|
||
'kb-product': 0.5,
|
||
'kb-faq': 0.3,
|
||
'kb-manual': 0.2
|
||
}
|
||
})
|
||
```
|
||
|
||
## 📊 知识库管理
|
||
|
||
### 查看统计
|
||
|
||
```typescript
|
||
const stats = await client.ai.getKnowledgeBaseStats(knowledgeBase.id)
|
||
|
||
console.log('文档数:', stats.document_count)
|
||
console.log('块数:', stats.chunk_count)
|
||
console.log('总 token 数:', stats.total_tokens)
|
||
```
|
||
|
||
### 更新文档
|
||
|
||
```typescript
|
||
// 重新上传会自动更新
|
||
await client.ai.updateDocument(doc.id, {
|
||
file: './docs/user-guide-v3.pdf'
|
||
})
|
||
```
|
||
|
||
### 删除文档
|
||
|
||
```typescript
|
||
await client.ai.deleteDocument(doc.id)
|
||
```
|
||
|
||
## 🧪 最佳实践
|
||
|
||
### 文档准备
|
||
|
||
1. ✅ 清理格式，移除无关内容
|
||
2. ✅ 添加目录和标题结构
|
||
3. ✅ QA 格式文档效果最好
|
||
4. ❌ 避免过长的无结构文本
|
||
5. ❌ 避免大量表格（难以正确分块）
|
||
|
||
### 检索优化
|
||
|
||
```typescript
|
||
// 调整检索参数
|
||
const optimalConfig = {
|
||
topK: 3, // 不要太多，可能引入噪音
|
||
scoreThreshold: 0.75, // 设置合理阈值
|
||
enableRerank: true // 启用重排序
|
||
}
|
||
```
|
||
|
||
### Prompt 工程
|
||
|
||
```typescript
|
||
const response = await client.ai.ask({
|
||
knowledgeBaseId: knowledgeBase.id,
|
||
question: '...',
|
||
systemPrompt: `你是一个专业客服，请基于给定的知识库内容回答用户问题。
|
||
- 如果知识库中没有相关内容，请如实告知
|
||
- 回答要简洁、专业、易懂
|
||
- 适当引用原文帮助用户理解`
|
||
})
|
||
```
|
||
|
||
## ❓ 常见问题
|
||
|
||
### Q: 检索不到相关内容？
|
||
|
||
1. 检查文档是否处理完成（状态为 `ready`）
|
||
2. 降低 `scoreThreshold` 阈值
|
||
3. 尝试 `hybridSearch: true` 混合搜索
|
||
4. 增加 `topK` 获取更多候选
|
||
|
||
### Q: 回答不准确？
|
||
|
||
1. 检查源文档质量
|
||
2. 调整 `chunkSize`，太小可能丢失上下文
|
||
3. 启用 `rerank` 提高相关性
|
||
4. 优化 system prompt
|
||
|
||
### Q: 处理速度慢？
|
||
|
||
- 小文档使用更快的 embedding 模型
|
||
- 避开高峰期处理大批量文档
|
||
- 使用异步处理（Webhooks 通知）
|
||
|
||
---
|
||
|
||
**上一步：** [REST API 完整参考](./api-reference.md)
|
||
**下一步：** [AI 工作流配置](./workflow.md)
|