Skip to content

knowledge-base-sync.md

Latest commit

 

History

History
238 lines (185 loc) · 7.22 KB

knowledge-base-sync.md

File metadata and controls

238 lines (185 loc) · 7.22 KB

飞书知识库同步指南

本文档详细介绍如何配置和使用飞书知识库同步功能，实现飞书云文档到FastGPT知识库的自动同步。

目录

功能概述

飞书知识库同步功能提供以下能力：

核心功能

  • 文档内容同步：自动同步飞书云文档(docx)内容到FastGPT知识库
  • 多维表格同步：支持飞书多维表格(sheet)内容同步
  • 图片提取处理：自动提取文档中的图片并生成描述
  • 知识库描述生成：基于LLM自动生成知识库描述
  • 增量同步：支持文档变更的增量同步
  • 批量同步：支持批量导入整个知识空间

支持的文档类型

  • 飞书云文档（docx）
  • 飞书多维表格（sheet）
  • 飞书文件（file - .docx/.pdf/.xlsx/.pptx/.md）

权限配置

必需的飞书应用权限

在飞书开放平台中申请以下权限：

文档权限

docs:read          # 读取文档内容
docs:write         # 写入文档内容（可选）
docx:read          # 读取云文档内容
docx:write         # 写入云文档内容（可选）

知识库权限

wiki:read          # 读取知识库内容
wiki:write         # 写入知识库内容（可选）
space:read         # 读取空间信息
space:write        # 管理空间（可选）

文件权限

drive:read         # 读取云盘文件
drive:write        # 写入云盘文件（可选）

权限申请步骤

  1. 登录飞书开放平台
  2. 创建企业自建应用
  3. 进入应用详情页 → 权限管理
  4. 搜索并添加上述权限
  5. 提交审核，等待管理员审批
  6. 发布应用版本

配置文件设置

基础配置

{
    "FEISHU_APPS": [
        {
            "dataset_sync": true,                            // 启用知识库同步
            "app_id": "cli_a0163xxx",                       // 飞书应用ID
            "app_secret": "v11k8wGEOdxxx",                  // 飞书应用密钥
            "app_name": "知识库同步应用",                    // 应用名称
            "fastgpt_url": "http://127.0.0.1:3000",        // FastGPT服务地址
            "fastgpt_key": "fastgpt-aQ3Vr4M8Sxxx",         // FastGPT API密钥
            "vector_model": "m3e-base",                      // 向量化模型
            "agent_model": "qwen3-8b"                     // 对话模型
        }
    ]
}

图片处理配置（可选）

{
    "image_bed_base_url": "http://127.0.0.1:8000",                    // 图床服务地址
    "image_bed_vlm_api_url": "https://api.siliconflow.cn/v1/chat/completions", // 图像理解API
    "image_bed_vlm_api_key": "sk-xxxxx",                              // 图像理解API密钥
    "image_bed_vlm_model": "Pro/Qwen/Qwen2.5-VL-7B-Instruct",                 // 视觉语言模型
    "image_bed_vlm_model_prompt": "请用20字以内简洁描述这张图片内容，不要加任何前缀，直接给出描述，参考论文引用图例的格式。"
}

知识库描述生成配置（可选）

{
    "summary_llm_api_url": "https://api.siliconflow.cn/v1/chat/completions", // 摘要生成API
    "summary_llm_api_key": "sk-xxxxx",                                       // 摘要生成API密钥
    "summary_llm_model": "Qwen/Qwen3-32B"                                  // 摘要生成模型
}

同步流程

1. 自动同步

启用事件订阅后，系统会自动监听文档变更事件：（5分钟级小同步）

  1. 文档更新事件：当用户修改文档时自动触发同步
  2. 文档创建事件：新文档创建时自动添加到知识库
  3. 文档删除事件：文档删除时从知识库中移除

3. 定时同步

配置定时任务进行批量同步：（1小时大同步，飞书事件失败兜底）

# 示例：每小时同步一次知识库
@scheduler.scheduled_job('interval', hours=1)
def sync_wiki_spaces():
    for app_config in feishu_apps:
        if app_config.get('dataset_sync'):
            sync_all_wiki_spaces(app_config)

同步机制详解

1. 文档内容提取

云文档（docx）

  • 提取文档标题、正文内容
  • 解析文档结构（标题层级）
  • 提取表格数据
  • 处理内嵌图片

多维表格（sheet）

  • 提取表格数据
  • 保持数据结构关系
  • 处理公式和函数

2. 图片处理流程

  1. 图片提取：从文档中提取所有图片
  2. 图片上传：上传到配置的图床服务
  3. 内容识别：使用VLM模型识别图片内容
  4. 描述生成：生成简洁的图片描述
  5. 内容替换：将图片替换为描述文本

3. 向量化处理

  1. 文本分块：将长文档分成适当大小的文本块
  2. 向量生成：使用配置的向量模型生成嵌入向量
  3. 存储索引：将向量存储到FastGPT知识库

4. 增量同步策略

  • 文档版本比较：比较文档修改时间
  • 内容哈希校验：检查内容是否真正发生变化
  • 差异化更新：只更新变化的文档部分

常见问题

Q1: 同步失败，提示权限不足

解决方案：

  1. 检查飞书应用权限是否正确配置
  2. 确认应用已发布且权限已生效
  3. 验证用户是否有访问对应文档/知识库的权限

Q2: 图片无法正确处理

解决方案：

  1. 检查图床服务是否正常运行
  2. 验证VLM API配置是否正确
  3. 确认图片格式是否支持

Q3: FastGPT知识库创建失败

解决方案：

  1. 检查FastGPT服务连接是否正常
  2. 验证API密钥是否有效
  3. 确认向量模型配置是否正确

Q4: 同步速度较慢

解决方案：

  1. 调整并发同步数量
  2. 优化文档分块大小
  3. 使用更快的向量化模型

Q5: 文档格式不支持

解决方案：

  1. 检查文档类型是否在支持列表中
  2. 对于不支持的格式，考虑转换为支持的格式
  3. 提交功能需求，扩展支持的文档类型

最佳实践

1. 批量同步策略

  • 在非工作时间进行大规模同步
  • 分批次同步，避免API限流
  • 监控同步进度和错误日志

2. 性能优化

  • 合理设置文档分块大小（建议512-1024字符）
  • 使用高效的向量化模型
  • 启用缓存机制减少重复处理

3. 错误处理

  • 设置重试机制处理临时网络错误
  • 记录详细的错误日志便于排查
  • 建立告警机制及时发现问题

4. 数据管理

  • 定期清理过期的同步任务记录
  • 备份重要的知识库数据
  • 监控存储空间使用情况

技术架构

同步服务架构

飞书API ←→ 同步服务 ←→ FastGPT API
    ↓           ↓           ↓
  权限验证    内容处理    知识库管理
  文档获取    图片处理    向量存储
  事件监听    格式转换    检索优化

数据流转

飞书文档 → 内容提取 → 格式转换 → 图片处理 → 文本分块 → 向量化 → FastGPT存储

通过以上配置和使用，您可以实现飞书知识库到FastGPT的完整同步功能，为您的团队提供强大的知识管理和智能问答能力。