这个项目向量知识库怎么使用？

好的！我来详细介绍项目中向量知识库的完整使用方法。

* * *

# ? 向量知识库使用指南

## 一、知识库概览

当前知识库状态：

指标

数量

总文档数

31

总文本块

261

文集数

6

### 各文集统计

文集名称

文档数

文本块数

架构设计

0

开发指南

3

100

功能文档

0

重构迁移

1

40

版本管理

3

87

项目整体

24

34

* * *

## 二、导入文档到知识库

### 方法 1：使用导入脚本（推荐）

#### 基本用法

```bash
# 进入项目根目录
cd /workspace/projects

# 导入所有文档（增量模式）
npx tsx scripts/knowledge-import.ts

# 强制重新导入所有文件
npx tsx scripts/knowledge-import.ts --force

# 禁用增量更新（全量导入）
npx tsx scripts/knowledge-import.ts --no-incremental

# 详细输出模式
npx tsx scripts/knowledge-import.ts --verbose
```

#### 参数说明

参数

简写

说明

默认值

`--force`

`-f`

强制重新导入所有文件

`false`

`--no-incremental`

`-n`

禁用增量更新模式

`true`

`--dir <dir>`

`-d`

指定根目录

当前目录

`--verbose`

`-v`

详细输出模式

`false`

#### 预期输出

```plaintext
========================================
  智能知识库导入工具
========================================

导入配置:
  根目录: /workspace/projects
  增量更新: true
  强制重导: false
  包含模式: docs/**/*.md, README.md
  排除模式: node_modules, .next, .git, dist, build

文集配置:
  - 架构设计 (payroll_architecture_collection): /docs/(dev/)?architecture|/docs/(dev/)?structure
  - 开发指南 (payroll_development_collection): /docs/(dev/)?(standards|techstack|database|api)
  ...

========================================

总计文件: 15
成功导入: 12
跳过文件: 2
失败文件: 1
```

* * *

### 方法 2：使用 API 接口

#### 触发导入

```bash
curl -X POST http://localhost:5000/api/knowledge/import \
  -H "Content-Type: application/json" \
  -d '{
    "force": false,
    "incremental": true
  }'
```

#### 响应示例

```json
{
  "code": 0,
  "message": "导入完成",
  "data": {
    "success": true,
    "totalFiles": 15,
    "importedFiles": 12,
    "skippedFiles": 2,
    "failedFiles": 1,
    "errors": [],
    "details": [
      {
        "file": "/path/to/file.md",
        "collectionId": "payroll_architecture_collection",
        "status": "imported",
        "message": "文档ID: xxx"
      }
    ]
  }
}
```

* * *

### 方法 3：导入项目版本历史

```bash
# 导入项目版本历史到知识库
npx tsx scripts/update-knowledge-base.ts
```

* * *

## 三、搜索知识库

### 方法 1：使用 API 接口（推荐）

#### 基本搜索

```bash
# 搜索所有文集
curl -X GET "http://localhost:5000/api/knowledge/search?query=前端架构&topK=5&threshold=0.3"

# 搜索特定文集
curl -X GET "http://localhost:5000/api/knowledge/search?query=开发环境配置&datasets=payroll_development_collection&topK=3"

# POST 方式搜索
curl -X POST http://localhost:5000/api/knowledge/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "工资条功能",
    "datasets": ["payroll_features_collection"],
    "topK": 5,
    "threshold": 0.3
  }'
```

#### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "query": "前端架构",
    "datasets": ["payroll_architecture_collection"],
    "topK": 5,
    "threshold": 0.3,
    "results": [
      {
        "content": "...文档内容...",
        "score": 0.95,
        "metadata": {
          "title": "前端架构设计",
          "collectionId": "payroll_architecture_collection"
        }
      }
    ],
    "total": 5
  }
}
```

#### 参数说明

参数

类型

说明

默认值

`query`

string

搜索查询（必需）

\-

`datasets`

string/array

指定文集

所有文集

`topK`

number

返回结果数量

5

`threshold`

number

最小相关度阈值（0-1）

0.3

* * *

### 方法 2：在代码中使用

```typescript
import { KnowledgeClient, Config } from 'coze-coding-dev-sdk';

// 创建知识库客户端
const config = new Config();
const client = new KnowledgeClient(config);

// 搜索特定文集
async function searchArchitecture() {
  const response = await client.search(
    "前端架构设计",
    ["payroll_architecture_collection"],
    5,    // 返回前5个结果
    0.5   // 最小相关度阈值
  );

if (response.code === 0) {
    response.chunks.forEach(chunk => {
      console.log(`相关度: ${(chunk.score * 100).toFixed(1)}%`);
      console.log(`内容: ${chunk.content}`);
      console.log(`文集: ${chunk.metadata?.collectionId}\n`);
    });
  }
}

// 搜索多个文集
async function searchMultiple() {
  const response = await client.search(
    "工资条",
    [
      "payroll_features_collection",
      "payroll_migration_collection"
    ],
    10,
    0.4
  );
  // 处理结果...
}
```

* * *

## 四、知识库管理

### 1\. 查看统计信息

```bash
# 获取知识库统计
curl http://localhost:5000/api/knowledge/stats
```

#### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "totalDocuments": 31,
    "totalChunks": 261,
    "collections": [
      {
        "id": "payroll_development_collection",
        "name": "开发指南",
        "documentCount": 3,
        "chunkCount": 100
      }
    ],
    "lastUpdated": "2026-02-12T16:55:32.723Z"
  }
}
```

* * *

### 2\. 获取文集文档列表

```bash
# 获取指定文集的文档列表
curl "http://localhost:5000/api/knowledge/collection-docs?collectionId=payroll_development_collection"
```

* * *

### 3\. 获取文档内容

```bash
# 获取文档的完整内容
curl "http://localhost:5000/api/knowledge/document-content?documentId=xxx"
```

* * *

## 五、实际使用场景

### 场景 1：AI 助手增强

让 AI 助手基于知识库回答项目相关问题：

```typescript
// 用户问题
const question = "如何配置开发环境？";

// 1. 从知识库搜索相关文档
const response = await client.search(question, ["payroll_development_collection"], 3);

// 2. 构建上下文
const context = response.chunks.map(chunk => chunk.content).join('\n\n');

// 3. 将上下文传递给 AI
const aiResponse = await aiChat(`
基于以下信息回答问题：

${context}

问题：${question}
`);
```

* * *

### 场景 2：快速文档查找

在代码编辑器中快速查找相关文档：

```typescript
// 获取当前代码上下文
const codeContext = getCurrentCodeContext();

// 搜索相关文档
const docs = await client.search(
  codeContext,
  ["payroll_development_collection"],
  3
);

// 显示相关文档片段
docs.forEach(doc => {
  console.log(`相关度: ${(doc.score * 100).toFixed(1)}%`);
  console.log(doc.content);
});
```

* * *

### 场景 3：新员工入职

为新员工提供智能文档问答系统：

```typescript
// 新员工提出问题
const newQuestion = "项目使用了哪些技术栈？";

// 搜索相关文档
const answer = await searchKnowledgeBase(newQuestion);

// 返回答案和相关文档
return {
  answer: answer.summary,
  relatedDocs: answer.chunks,
  confidence: answer.maxScore
};
```

* * *

## 六、文集分类说明

### 文集配置

文集 ID

名称

路径模式

用途

`payroll_architecture_collection`

架构设计

`/(dev/)?architecture|structure`

架构设计文档

`payroll_development_collection`

开发指南

`/(dev/)?(standards|techstack|database|api)`

开发指南

`payroll_features_collection`

功能文档

`/features`

功能需求

`payroll_migration_collection`

重构迁移

`/(migration|refactor|simplify)`

迁移文档

`payroll_version_collection`

版本管理

`/(version|changelog)`

版本历史

`payroll_project_collection`

项目整体

`/(overview|project|readme)`

项目说明

* * *

## 七、最佳实践

### 1\. 文档编写

*   使用清晰的标题结构
*   添加适当的标签和分类
*   保持文档简洁明了
*   定期更新文档内容

### 2\. 搜索技巧

*   使用自然语言提问
*   尝试不同的关键词组合
*   指定相关文集提高准确度
*   调整 `threshold` 参数控制结果质量

### 3\. 知识库维护

*   定期导入新文档
*   使用增量更新避免重复处理
*   监控导入失败日志
*   定期清理过时文档

* * *

## 八、常见问题

### Q1: 搜索结果不准确怎么办？

**A**:

1.  尝试使用更具体的关键词
2.  降低 `threshold` 参数获取更多结果
3.  指定相关文集缩小搜索范围
4.  检查文档内容是否完整

* * *

### Q2: 如何重新导入所有文档？

**A**:

```bash
# 使用 --force 参数
npx tsx scripts/knowledge-import.ts --force
```

* * *

### Q3: 知识库支持哪些文档格式？

**A**: 目前主要支持 **Markdown (.md)** 格式。

* * *

### Q4: 如何添加新的文集？

**A**: 修改 `src/lib/knowledge/SmartKnowledgeImporter.ts` 中的 `getDefaultCollections()` 函数：

```typescript
export function getDefaultCollections(): CollectionConfig[] {
  return [
    // 现有配置
    {
      id: 'new_collection',
      name: '新文集',
      pathPattern: '/docs/new-section',
      priority: 10,
    },
    // ...
  ];
}
```

* * *

## 九、快速开始示例

### 完整工作流程

```bash
# 1. 进入项目目录
cd /workspace/projects

# 2. 导入文档到知识库
npx tsx scripts/knowledge-import.ts

# 3. 查看知识库统计
curl http://localhost:5000/api/knowledge/stats

# 4. 搜索文档
curl -X GET "http://localhost:5000/api/knowledge/search?query=前端架构&topK=5"
```

* * *

## 十、相关资源

*   [智能知识库导入指南](https://code.coze.cn/workspace/projects/docs/11-AI%E7%B3%BB%E7%BB%9F/%E6%99%BA%E8%83%BD%E7%9F%A5%E8%AF%86%E5%BA%93%E5%AF%BC%E5%85%A5%E6%8C%87%E5%8D%97.md)
*   [知识库导入指南](https://code.coze.cn/workspace/projects/docs/11-AI%E7%B3%BB%E7%BB%9F/%E7%9F%A5%E8%AF%86%E5%BA%93%E5%AF%BC%E5%85%A5%E6%8C%87%E5%8D%97.md)
*   [AI 记忆系统使用指南](https://code.coze.cn/workspace/projects/docs/11-AI%E7%B3%BB%E7%BB%9F/%E8%AE%B0%E5%BF%86%E7%B3%BB%E7%BB%9F%E6%8C%87%E5%8D%97.md)