进阶 docs.openwebui.com 2026-10-22 19:22:27 · 25 阅读

第6章 oikb:面向 Open WebUI 的知识库增量同步工具

知识库同步(oikb)

让知识库自动与数据源保持同步。 oikb 是用于将内容镜像到知识库的官方配套工具。只需指向本地文件夹、GitHub 仓库、Confluence 空间、S3 存储桶或其 44 个连接器中的任意一个,它即可确保知识库内容始终最新。 与一次性上传不同(数据源一旦变化,上传的内容便会过时),oikb 执行增量同步:它将知识库与动态数据源建立一次连接,随后按计划、在每次推送或按需时保持其更新。文档仓库、Wiki、存储桶等数据源均能在无人值守的情况下保持最新状态。 它是一个独立的程序(包含命令行工具和可选的常驻守护进程),不属于 Open WebUI 服务器,但专为 Open WebUI 构建,并通过标准的 REST API 与其通信。 需要 Open WebUI 0.9.6 及以上版本。oikb 驱动 v0.9.6 中新增的增量同步端点(POST /api/v1/knowledge/{id}/sync/diff 和 .../sync/cleanup)。针对旧版本服务器,oikb 无可调用的接口。这些端点的服务器端实现文档位于“知识 → 同步本地目录”章节。

为何需要知识库同步? 仅传输变更内容 每个文件都会计算 SHA-256 哈希值,并与服务器已有内容比对,因此仅上传新增和修改的文件,并移除已删除的文件。包含 10,000 个文件的仓库若无变化,重新同步仅需数秒,因为无需重新上传或重新嵌入。频繁运行几乎不产生额外成本。 专为大型资料库设计 应用内的“同步目录”功能在浏览器中运行,面对大量数据(数千个文件或多千兆字节的资料库)时会变慢且进度反馈有限。oikb 原生运行,提供进度条、并行上传和重试机制,能够可靠地同步数万文件的大型资料库。如果语料库较大,这是推荐的加载方式。 一个工具,连接所有数据源 支持本地文件夹、Git 仓库、Confluence 或 Notion 空间、S3 存储桶、Jira 项目、Slack 频道以及另外 30 多种源。相同的命令和增量引擎适用于所有数据源。 自动保持最新 可手动同步一次,或交给守护进程按间隔、cron 定时或在有人推送的瞬间自动运行。与动态数据源连接的知识库不会悄悄过时。 模型可驱动同步 守护进程兼作 OpenAPI 工具服务器,模型可在对话中触发重新同步并反馈结果,无需人工操作命令行。

核心特性 ⚡ 增量同步:通过 SHA-256 差异比对,仅上传新增和修改的文件;移除已删除文件,保持不变文件不受影响 🌐 44 个连接器:支持本地文件夹、Git、云存储、Wiki、工单、聊天、CRM 及网页爬虫 ⏱️ 计划与 Webhook 同步:通过守护进程按间隔、cron 或在推送瞬间运行 👀 监视模式:在每次保存时自动同步本地文件夹 🎯 选择性同步:支持包含/排除通配符、大小限制,并将单一数据源拆分到多个知识库 🤖 模型可触发:守护进程作为 OpenAPI 工具服务器,模型可在聊天中启动和检查同步 🔑 使用您的权限:以您的用户身份进行身份验证,绝不绕过知识库访问控制 📊 生产就绪:提供 Prometheus 指标、结构化 JSON 日志、同步历史及故障通知

安装 pip install oikb 需要 Python 3.11+ 和 Open WebUI 0.9.6+ 服务器。大多数连接器使用纯 HTTP 通信,无需额外依赖。少数连接器需要安装可选的厂商 SDK 扩展: pip install oikb[s3] # Amazon S3 pip install oikb[gcs] # Google Cloud Storage pip install oikb[azure] # Azure Blob pip install oikb[dropbox] # Dropbox pip install oikb[gdrive] # Google Drive pip install oikb[all] # 一次性安装所有可选连接器 完整的扩展列表包括 s3、gcs、azure、dropbox、r2、gdrive、gmail、gsites、web、oracle、sharepoint-cert 和 all。未在此列出的连接器(GitHub、Confluence、Notion、Jira、Slack 及大多数其他)无需额外安装。 在生产环境中,Docker 镜像已发布在 ghcr.io/open-webui/oikb。请参见“运行守护进程”章节。

快速开始 export OPEN_WEBUI_URL=http://localhost:3000 export OPEN_WEBUI_API_KEY=sk-your-api-key # 设置 → 账户 → API 密钥

# 将本地文件夹同步到知识库 oikb sync ./docs --kb-id your-kb-id

# 或同步 GitHub 仓库,无需本地克隆 oikb sync github:owner/repo --kb-id your-kb-id

# 预览将要发生的变更,但不上传任何内容 oikb sync ./docs --kb-id your-kb-id --dry-run --kb-id 是知识库的 ID,即工作区中知识库 URL 里的 UUID(.../knowledge/)。同一命令运行两次,第二次不会做任何事:仅处理内容发生变化的文件。

同步过程示例 首次运行会上传所有内容;之后每次运行仅移动发生变化的部分: $ oikb sync github:acme/handbook --kb-id 8f3a2b1c-... 找到 1,204 个文件 差异:+3, ~1, -2, 1198 个未变更 上传中 ━━━━━━━━━━━━━━━━━━━ 4/4 • 0:00:02 同步完成:3 个新增,1 个修改,2 个删除,1198 个未变更 “差异”行是服务器对“实际发生了什么变化”的回答:3 个新文件,1 个修改,2 个删除,1,198 个保持不变。 权限即你的权限。API 密钥以您的用户身份进行认证。oikb 只能读写该用户已拥有权限的知识库。它不是管理员后门,也不绕过访问控制。

保存凭据 为避免每条命令都重复输入 URL 和密钥: oikb config set url http://localhost:3000 oikb config set token sk-your-api-key oikb config get # 显示已保存的内容(令牌会被掩码显示) 配置保存在 ~/.config/oikb/config.yaml(可通过 OIKB_CONFIG_DIR 环境变量覆盖目录)。解析顺序(优先级从高到低): 1. CLI 参数(--url, --token) 2. 环境变量(OPEN_WEBUI_URL, OPEN_WEBUI_API_KEY) 3. 配置文件

增量同步工作原理 oikb 扫描数据源并计算每个文件的 SHA-256 校验和。 它将该清单(路径、文件名、校验和及大小,而非文件内容)发送到 Open WebUI 的 /sync/diff 端点。服务器会回复具体新增、修改和删除的内容,以及需要创建或删除的目录。此调用是只读的,不会改变知识库。 oikb 删除过期文件(及变为空的目录),创建缺失的目录,然后仅上传新增和修改的文件,每个文件都标记其哈希值,以便服务器跳过重新哈希。在服务器端,清理操作会删除过期文件的记录及存储字节,除非满足以下条件:ENABLE_KNOWLEDGE_FILE_RETENTION=true、文件仍链接到另一个知识库、或密钥所属用户既非文件所有者也非管理员。在 0.9.6 之前上传的文件没有存储校验和,因此在首次同步时会被报告为已修改,随后被替换,之后则保持不变。 由于差异比对基于内容哈希,未变化的仓库重新同步几乎瞬间完成:无重新上传、提取或嵌入,因此频繁运行没有成本。只有实际变更才会产生工作负载。 上传期间的临时服务器错误(HTTP 5xx)会进行最多三次指数退避重试。上传默认顺序执行;传入 --concurrency N(或在配置项中设置 concurrency:)可并行上传 N 个文件,适用于大型同步。 相应的服务器端行为以及为自定义脚本暴露的两个端点文档位于“知识 → 同步本地目录”和“知识 → API 访问”章节。oikb 是维护中的客户端,实现了完整循环,并在此基础上增加了计划、Webhooks 和 44 个连接器。

数据源与连接器 数据源可以是本地路径或“scheme:target”字符串。oikb 将 scheme 解析为连接器,拉取文件并将其同步到知识库。凭据绝不写入数据源字符串或 .oikb.yaml;每个连接器从环境变量读取凭据,以确保机密信息不留在配置文件中(配合 ${VAR} 插值使用,保持配置文件可提交版本控制)。 下表中的 [方括号] 标记数据源字符串的可选部分。

分组 | 连接器 | 数据源字符串 | 凭据(环境变量) 本地 | 本地目录 | ./path(任意文件系统路径) | 无 代码 | GitHub | github:owner/repo | GITHUB_TOKEN(私有仓库) 代码 | GitLab | gitlab:owner/repo | GITLAB_TOKEN, GITLAB_URL(自托管) 代码 | Bitbucket | bitbucket:owner/repo | BITBUCKET_USER, BITBUCKET_APP_PASSWORD 云存储 | Amazon S3 | s3://bucket/prefix | 标准 AWS 凭据链(boto3) 云存储 | Google Cloud Storage | gs://bucket/prefix | GOOGLE_APPLICATION_CREDENTIALS 云存储 | Azure Blob | az://container/prefix | AZURE_STORAGE_CONNECTION_STRING 云存储 | Cloudflare R2 | r2://bucket/prefix | R2_ACCOUNT_ID, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY 云存储 | Oracle Cloud | oci://bucket/prefix | OCI_NAMESPACE + OCI SDK 配置 云存储 | Dropbox | dropbox:/path | DROPBOX_TOKEN 云存储 | Google Drive | gdrive:folder_id | GOOGLE_APPLICATION_CREDENTIALS 云存储 | SharePoint | sharepoint:site[/library] | SHAREPOINT_TENANT_ID, SHAREPOINT_CLIENT_ID 和 SHAREPOINT_CLIENT_SECRET 或 SHAREPOINT_CERTIFICATE_PATH 云存储 | Egnyte | egnyte:/path | EGNYTE_DOMAIN, EGNYTE_TOKEN Wiki & KB | Confluence | confluence:SPACE | CONFLUENCE_URL, CONFLUENCE_USER, CONFLUENCE_TOKEN Wiki & KB | Notion | notion:root_id | NOTION_TOKEN Wiki & KB | BookStack | bookstack:BOOK_ID | BOOKSTACK_TOKEN_ID, BOOKSTACK_TOKEN_SECRET Wiki & KB | Discourse | discourse:[category] | DISCOURSE_URL, DISCOURSE_API_KEY, DISCOURSE_API_USERNAME Wiki & KB | GitBook | gitbook:space_id | GITBOOK_TOKEN Wiki & KB | Guru | guru:[collection] | GURU_USER, GURU_TOKEN Wiki & KB | Outline | outline:[collection] | OUTLINE_URL, OUTLINE_TOKEN Wiki & KB | Slab | slab:[org] | SLAB_ORG, SLAB_TOKEN Wiki & KB | Document360 | document360:project_id | DOCUMENT360_TOKEN Wiki & KB | DokuWiki | dokuwiki:[namespace] | DOKUWIKI_URL, DOKUWIKI_USER, DOKUWIKI_PASSWORD Wiki & KB | Google Sites | gsites:site_id | GOOGLE_SITES_TOKEN 工单 | Jira | jira:PROJECT | JIRA_URL, JIRA_USER, JIRA_TOKEN 工单 | Linear | linear:team_key | LINEAR_TOKEN 工单 | Zendesk | zendesk:[subdomain] | ZENDESK_SUBDOMAIN, ZENDESK_USER, ZENDESK_TOKEN 工单 | Freshdesk | freshdesk:[domain] | FRESHDESK_DOMAIN, FRESHDESK_TOKEN 工单 | Asana | asana:project_id | ASANA_TOKEN 工单 | ClickUp | clickup:space_id | CLICKUP_TOKEN 工单 | Airtable | airtable:base_id[/table] | AIRTABLE_TOKEN 工单 | ServiceNow | servicenow:[table] | SERVICENOW_INSTANCE, SERVICENOW_USER, SERVICENOW_PASSWORD 工单 | ProductBoard | productboard: | PRODUCTBOARD_TOKEN 消息 | Slack | slack:channel_id | SLACK_TOKEN 消息 | Discord | discord:channel_id | DISCORD_TOKEN 消息 | Microsoft Teams | teams:team_id/channel_id | TEAMS_TENANT_ID, TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET 消息 | Gmail | gmail:[email] | GOOGLE_APPLICATION_CREDENTIALS 消息 | Zulip | zulip:[stream] | ZULIP_URL, ZULIP_EMAIL, ZULIP_KEY 会议 | Gong | gong: | GONG_ACCESS_KEY, GONG_ACCESS_KEY_SECRET 会议 | Fireflies | fireflies: | FIREFLIES_TOKEN 销售 & CRM | Salesforce | salesforce: | SALESFORCE_URL, SALESFORCE_TOKEN 销售 & CRM | HubSpot | hubspot: | HUBSPOT_TOKEN 论坛 | XenForo | xenforo:[forum_id] | XENFORO_URL, XENFORO_KEY Web | 网站 / sitemap | web:https://example.com | 无

值得了解的连接器注意事项: GitHub 通过 Trees API 读取,因此无需本地克隆。添加 --branch 和 --path(或在配置中使用 branch: / path:)以指定分支或子目录。 聊天连接器(Slack、Discord、Teams)按天分割历史记录,使同步真正具备增量特性:过去天数的记录不可变,其校验和永不改变,因此永不重新上传。 Jira 和 ServiceNow 接受数据源字符串中的额外选项(查询、字段、输出格式、结果限制),例如 servicenow:incident?query=...&limit=500。各连接器的完整选项请参见 oikb 仓库。

过滤同步内容 使用包含/排除通配符和大小限制缩小数据源范围。这些选项位于 .oikb.yaml 的 filter: 下: sources: - name: docs source: github:owner/repo kb-id: your-kb-id filter: include: ["docs//*.md", "*.txt"] # 仅包含这些 exclude: ["drafts/", "/*.tmp"] # 排除这些(在包含之后应用) max-size: 50mb # 跳过超过此大小的文件 max-size 接受 b、kb、mb、gb 单位。超大文件会在差异比对前发出警告并跳过,因此不会上传。也可作为 CLI 标志使用:oikb sync ./docs --kb-id abc --max-file-size 50mb。当管理员设置了限制时,Open WebUI 也会强制执行其自身限制(默认均不设置):超过管理员“最大上传大小”(RAG_FILE_MAX_SIZE,单位 MB)的文件会被 HTTP 413 拒绝,不在“允许的文件扩展名”(RAG_ALLOWED_FILE_EXTENSIONS)范围内的扩展名会被 HTTP 400 拒绝,因此此类文件在每次同步中都会失败,除非您在此处将其过滤掉。 若要将同一数据源的不同部分路由到不同的知识库,请使用具有不同 filter.include 和 kb-id 的独立条目: sources: - name: user-docs source: github:owner/repo kb-id: abc123 filter: { include: ["docs/"] } - name: api-reference source: github:owner/repo kb-id: def456 filter: { include: ["api/"] }

跳过的文件与 .oikbignore 同步本地目录时,oikb 始终跳过隐藏条目(以 . 开头的任何项)和内置列表:.git、.svn、.hg、.DS_Store、Thumbs.db、__pycache__、.pytest_cache、node_modules、.oikb、.env。 对于项目特定的排除项,在同步根目录放置 .oikbignore 文件。它使用 gitignore 风格的通配符(末尾的 / 仅匹配目录,开头的 / 锚定到根目录)。目前不支持 ! 否定规则。

监视模式 对于正在积极编辑的本地目录,watch 会在文件变更的瞬间重新同步: oikb watch ./docs --kb-id your-kb-id 它使用文件系统事件(而非轮询),防抖时间为 1 秒(可通过 --debounce 调整),并一直运行直到按 Ctrl+C 停止。适合实时笔记文件夹;对于远程或无人值守的场景,请使用守护进程。

CI 中的单次同步 Docker 镜像以单次命令运行,这使其成为 GitHub Actions 的理想步骤,用于在每次合并时将文档推送到知识库: - name: Sync docs to Open WebUI uses: docker://ghcr.io/open-webui/oikb:latest with: args: sync /github/workspace/docs --kb-id ${{ secrets.KB_ID }} env: OPEN_WEBUI_URL: ${{ secrets.OPEN_WEBUI_URL }} OPEN_WEBUI_API_KEY: ${{ secrets.OPEN_WEBUI_API_KEY }}

CLI 参考 oikb sync :从数据源到知识库的增量同步(--kb-id)。省略 可同步 .oikb.yaml 中的每个条目。 oikb sync --dry-run:预览新增/修改/删除的内容,但不上传。 oikb sync --concurrency N:并行上传 N 个文件(默认 1,顺序执行)。 oikb sync --max-file-size 50mb:跳过超过指定大小的文件。 oikb sync --name :在 .oikb.yaml 模式下,仅同步匹配的条目。 oikb diff --kb-id ID:预览变更(sync --dry-run 的别名)。 oikb watch

--kb-id ID:在变更时自动同步本地目录(--debounce)。 oikb init:交互式向导,用于生成 .oikb.yaml。 oikb validate:检查 .oikb.yaml 语法。添加 --deep 还可 Ping Open WebUI,验证 API 密钥并确认每个知识库是否存在。 oikb daemon:运行带有 HTTP API 的定时守护进程。 oikb ls --kb-id ID:列出知识库中的文件。 oikb status --kb-id ID:显示知识库的名称、文件数量和总大小。 oikb history:查看同步历史(--json, --errors, --kb-id, --clear --days N)。 oikb reset --kb-id ID:删除知识库中的所有文件(--keep-directories 保留文件夹结构)。需要确认提示。 oikb config set url|token :保存 Open WebUI URL 或 API 密钥。oikb config get 用于显示它们。 向任何命令添加 -q / --quiet 以抑制非错误输出(适用于脚本),添加 -v / --verbose 以获取每文件详情。 oikb reset 会删除知识库中的所有内容。reset 会移除目标知识库中的每个文件,而不仅是 oikb 上传的文件。这是唯一的破坏性命令。确认提示的存在是有原因的。

用例 始终最新的产品文档 将文档仓库(github:acme/docs)连接到知识库,并在 CI 中的每次合并或 Webhook 时同步。支持人员和客户查询的文档永远不会落后于最新提交。 大型个人或家庭资料库 一个组织良好的文件夹中包含数千个混合文档(PDF、Markdown、扫描件、记录)。将 oikb 指向资料库顶部,它将整个目录树(包含所有子目录)同步到单个知识库,家庭成员即可提问而无需知道答案在哪个子文件夹中。应用内同步在此规模下表现吃力;oikb 专为此时设计。 来自 Wiki 的公司手册 通过每日 cron 任务将 Confluence 空间或 Notion 工作区镜像到知识库。“询问 HR”模型基于最新手册回答,Wiki 中的编辑次日即现,无需任何人重新上传。 来自工单的支持知识 将已解决的 Zendesk 或 Jira 工单同步到知识库,使分类模型能够基于您的历史而非通用训练数据,展示类似问题之前的处理方式。 代码感知助手 通过过滤器将一个仓库拆分到两个知识库:docs/ 下的文本进入“文档”知识库,src/ 下的源码进入“代码”知识库。挂载适合模型的任一知识库,两者通过单一配置保持同步。

限制 需要 Open WebUI 0.9.6+ 增量同步端点在 v0.9.6 中引入。针对旧版本服务器,oikb 无可调用的接口。 守护进程作为单个进程运行 计划任务和每个知识库的锁位于单一进程中,因此守护进程旨在作为单个副本运行。若要覆盖更多数据源,请向一个守护进程添加条目,而非运行多个副本。 索引仍在服务器端进行 oikb 上传速度快,但 Open WebUI 会异步提取和嵌入每个新文件。文件存储后上传即返回;提取、嵌入及链接到知识库在后台任务中进行,GET /api/v1/files/{id}/process/status 报告文件完成或失败的状态。在此之前,该文件不会出现在知识库的文件列表中。

故障排除 连接拒绝或 401 Unauthorized:URL 或密钥错误或未设置。使用 oikb config get 或 echo $OPEN_WEBUI_URL 和 echo $OPEN_WEBUI_API_KEY 检查。密钥必须是有效的 Open WebUI API 密钥(设置 → 账户)。API 密钥默认关闭:管理员必须启用(ENABLE_API_KEYS),非管理员用户还需拥有 API 密钥权限,否则账户页面将不显示 API 密钥部分。 403 禁止访问:密钥有效但服务器禁用了 API 密钥,您的用户缺乏 API 密钥权限,端点限制已开启(ENABLE_API_KEYS_ENDPOINT_RESTRICTIONS)且 API_KEYS_ALLOWED_ENDPOINTS 未包含 /api/v1/knowledge 和 /api/v1/files,或您的用户对目标知识库没有写入权限。 未指定数据源且未找到 .oikb.yaml:运行 oikb sync 时未指定数据源且当前目录没有 .oikb.yaml。要么传入数据源(oikb sync ./docs --kb-id ...),要么使用 oikb init 创建配置。 大型同步缓慢:添加 --concurrency 4 进行并行上传,设置 filter.max-size 跳过大型二进制文件,并使用 filter.exclude 排除模型不需要的任何内容。 守护进程无法启动 / 知识库似乎缺失:运行 oikb validate --deep。它会验证服务器可达、API 密钥有效且配置中的每个 kb-id 确实存在。 知识库 ID 在哪里?在工作区打开知识库;UUID 是 URL 的最后一段路径,.../knowledge/。

另请参阅 运行守护进程 →:计划同步、Webhooks、HTTP API、可观测性、部署及允许模型触发同步。 知识:oikb 提供数据的知识库功能,包括服务器端同步端点。 OpenAPI / MCP 工具服务器:守护进程如何作为模型可调用的工具接入。 本内容仅供参考,不构成任何保证、担保或合同承诺。Open WebUI 按“原样”提供。请参阅您的许可证以获取适用条款。

评论 (0)