106 lines
9.2 KiB
Markdown
106 lines
9.2 KiB
Markdown
# LLMWiki × WeKnora 集成与部署
|
||
|
||
## 目标与边界
|
||
|
||
DeerFlow 只把 WeKnora 当作独立部署的知识抽取、向量化和检索服务，不复制或修改 WeKnora 前端，也不接管它的运行配置。
|
||
|
||
本版本按 WeKnora `v0.7.2` 的官方 REST API 实现；升级 WeKnora 大版本前应先回归下文列出的主要接口。
|
||
|
||
- WeKnora 自己负责 PostgreSQL、Redis、对象存储、解析器、向量库、Embedding/Rerank/LLM 等依赖。
|
||
- DeerFlow 只保存 WeKnora 连接地址，以及 DeerFlow 用户、发布状态、智能体绑定与 WeKnora 知识库之间的映射。
|
||
- DeerFlow 不保存也不发送 WeKnora API Key、Bearer Token 或其他 WeKnora 凭证；浏览器拿不到原始 WeKnora 知识库 ID。
|
||
- 用户权限、智能体所有权和页面风格全部沿用 DeerFlow；库所有者发布后立即进入公共 LLMWiki，不经过审核队列。
|
||
|
||
## 模式开关
|
||
|
||
`config.yaml` 中 `llmwiki.weknora.api_base_url` 非空时启用 WeKnora 模式；为空时继续使用原有 LLMWiki 页面和流程。
|
||
|
||
```yaml
|
||
llmwiki:
|
||
weknora:
|
||
api_base_url: "http://weknora-app:8080"
|
||
web_base_url: "http://weknora-app:8080"
|
||
```
|
||
|
||
管理员也可在 DeerFlow 原 LLMWiki 页面中的“集成配置”修改地址。页面配置是运行时覆盖项：启用覆盖并填写地址会切换到 WeKnora；启用覆盖但留空会强制回到原模式；“恢复配置文件设置”会重新采用 `config.yaml`。
|
||
|
||
这两个地址是 DeerFlow 中全部的 WeKnora 配置，不需要创建密钥文件，也不需要在 DeerFlow 中配置 WeKnora 的数据库、模型或存储参数。
|
||
|
||
## WeKnora 侧准备
|
||
|
||
先按 WeKnora 官方部署方式完整启动 WeKnora。数据库、Redis、MinIO/S3、解析服务和所有模型均在 WeKnora 自己的 compose、`.env` 或管理页面配置，DeerFlow 无对应字段。
|
||
|
||
DeerFlow 对 WeKnora 使用无凭证的内部 HTTP 请求，因此 `api_base_url` 必须指向可信内网服务，不能把匿名接口直接暴露到公网。需要在 WeKnora 自身或前置反向代理中，仅按容器网络、源 IP、安全组或 mTLS 等基础设施边界放行 DeerFlow。若 WeKnora 保持默认接口鉴权且未放行，连接测试会收到 401/403，并提示配置 WeKnora 或反向代理；DeerFlow 不提供凭证回退。
|
||
|
||
WeKnora 中至少需要一个可用且标为默认的 Embedding 模型。创建知识库时，DeerFlow 调用 WeKnora `/api/v1/models` 查找 `type=Embedding` 的默认模型，并把它的 ID 传给 WeKnora；因此 DeerFlow 不提供 `default_embedding_model_id` 配置。这个 ID 的含义是“新知识库使用哪个编码模型生成向量”，其生命周期属于 WeKnora。
|
||
|
||
WeKnora 侧放行范围需要覆盖本版本调用的模型读取、知识库管理、文档写入和知识检索接口。如果基础设施只放行检索接口，可以检索已有知识库，但无法通过 DeerFlow 创建知识库或上传文档。
|
||
|
||
## 数据与权限模型
|
||
|
||
DeerFlow 的 `llmwiki_knowledge_bases` 表保存以下控制面数据：DeerFlow 映射 ID、WeKnora ID、所有者用户 ID、名称快照和公开状态。文档、切片、向量和模型参数仍只存在 WeKnora。
|
||
|
||
- 个人库：仅所有者和 DeerFlow 管理员可管理。
|
||
- 公共库：所有者点击发布后立即公开，全部 DeerFlow 用户只读可检索；所有者可随时取消公开。
|
||
- 删除个人库时先删除 WeKnora 实体，再删除 DeerFlow 映射。
|
||
- 所有 BFF 接口和智能体工具都会按当前 DeerFlow 登录用户重新鉴权，不能靠前端提交任意知识库 ID 越权。
|
||
|
||
当前无凭证/反向代理方案使用一个固定的 WeKnora 服务身份。因此 DeerFlow 的用户隔离是映射层的逻辑隔离：不同 DeerFlow 用户只能看到自己拥有的库和已公开库；但这些库在 WeKnora 物理上都创建于该服务身份所属的同一个空间。上传文件不会落到 DeerFlow 用户目录，而是经 DeerFlow BFF 转发给 WeKnora，由 WeKnora 把文件对象、知识元数据、切片和向量分别写入自己的对象存储、数据库和向量存储。需要在 WeKnora 后台核对时，应登录这个服务身份所属空间，在“知识库管理”中按同名知识库进入查看。
|
||
|
||
如果要求 WeKnora 本身也按 DeerFlow 用户划分空间，则需要另一种部署：为每个 DeerFlow 用户建立 WeKnora 用户/租户并安全保存、轮换各自凭证。它与当前“不在 DeerFlow 配置 WeKnora 凭证”的单服务身份方案不同，不能只靠前端切换实现。
|
||
|
||
## 智能体和对话选择
|
||
|
||
智能体 `config.yaml` 可保存：
|
||
|
||
```yaml
|
||
llmwiki_knowledge_base_ids:
|
||
- "deerflow-mapping-id-1"
|
||
- "deerflow-mapping-id-2"
|
||
```
|
||
|
||
这里必须是 DeerFlow 映射 ID，不是 WeKnora 原始 ID。智能体创建页和详情编辑页均提供内嵌的“绑定知识空间”面板，可直接搜索、分组、多选、全选或清空当前用户有权读取的个人库和公共库，不再通过额外弹窗配置。
|
||
|
||
新建智能体对话时，页面只展示“智能体已绑定”且“当前登录用户仍有权读取”的交集，默认全选，可在发送第一条消息前调整或清空。普通新建对话也可选择知识库；选中了智能体时会自动切换成该智能体的绑定范围。问答选择器仿照 WeKnora 的交互结构，作为输入框工具栏的锚定下拉呈现，包含搜索、个人/公共分组、文档数量、多选、全选和清空，不再在输入框外单独占据一行。选择结果写入 LangGraph thread metadata 和运行 context，重新打开对话会恢复，开始对话后不可中途扩大权限范围。
|
||
|
||
`llmwiki_search` 是只读工具，只在 WeKnora 模式注册。每次调用会同时校验：
|
||
|
||
1. 当前对话选择；
|
||
2. 智能体允许的绑定范围；
|
||
3. 当前 DeerFlow 用户对映射的实时读取权限。
|
||
|
||
明确选择空列表表示本次对话不使用 LLMWiki；旧对话没有选择字段时，智能体对话默认使用其绑定范围，通用 Lead Agent 默认使用当前用户全部可见知识库。
|
||
|
||
## 前端实现
|
||
|
||
WeKnora 前端不做任何修改。DeerFlow 原“知识库资源管理”入口根据运行模式渲染：
|
||
|
||
- 原模式：保留现有 LLMWiki iframe 页面；
|
||
- WeKnora 模式：渲染 DeerFlow 原生 React 页面，提供个人库、公共库、直接发布和检索。点击卡片进入独立知识库路由，内容区复刻 WeKnora 的详情页结构，同时保留 DeerFlow 的导航、登录和权限壳。Wiki 库按 **Wiki → 文档 → 图谱** 排列并默认打开 Wiki；标准库不显示 Wiki 标签，按 **文档 → 图谱** 排列。Wiki 视图包含页面目录、搜索、页面正文和引用摘要；文档以卡片网格展示，点击后从右侧抽屉查看元数据、原文件与真实解析分块；图谱视图渲染 WeKnora Wiki 页面节点和边。新建知识库可选择“Wiki 知识库”或“标准知识库”，详情页支持文件、网页 URL、手工 Markdown 三种导入方式。问答选择器沿用 WeKnora 的紧凑搜索/分组/多选交互，颜色、间距和组件沿用 DeerFlow 设计系统；智能体创建和编辑页使用同一数据源的内嵌绑定面板。
|
||
|
||
问答检索命中以 DeerFlow 来源卡片展示。“查看原文”调用 DeerFlow 的 `/api/llmwiki/sources/context`，由服务端在重新校验 DeerFlow 用户权限后向 WeKnora 读取命中切片及相邻上下文，不向浏览器暴露 WeKnora 原始资源 ID。
|
||
|
||
## 主要接口
|
||
|
||
- `GET /api/llmwiki/runtime`：当前原模式/WeKnora 模式。
|
||
- `/api/system-settings/llmwiki`：管理员地址配置、重置和连通性测试。
|
||
- `/api/llmwiki/knowledge-bases`：知识库 CRUD、标准/Wiki 模式创建、详情、文档上传、解析、直接发布和取消公开。
|
||
- `POST /api/llmwiki/knowledge-bases/{id}/documents/url`：导入网页 URL。
|
||
- `POST /api/llmwiki/knowledge-bases/{id}/documents/manual`：发布手工 Markdown 内容。
|
||
- `GET /api/llmwiki/knowledge-bases/{id}/documents/{document_id}`：具体文档元数据。
|
||
- `GET /api/llmwiki/knowledge-bases/{id}/documents/{document_id}/preview`：鉴权后代理原文件预览。
|
||
- `GET /api/llmwiki/knowledge-bases/{id}/documents/{document_id}/chunks`：分页读取解析后的真实分块索引。
|
||
- `GET /api/llmwiki/knowledge-bases/{id}/graph`：读取 Wiki 页面图谱的节点和边；未开启 Wiki 索引时返回明确的空状态。
|
||
- `GET /api/llmwiki/knowledge-bases/{id}/wiki/pages` 与 `.../wiki/pages/{slug}`：读取 Wiki 页面目录和正文。
|
||
- `GET /api/llmwiki/agents/{agent_id}/knowledge-bases`：当前用户可用于该智能体的绑定交集。
|
||
- `POST /api/llmwiki/search`：页面检索。
|
||
- `GET /api/llmwiki/sources/context`：引用原文上下文。
|
||
|
||
## 验收建议
|
||
|
||
1. 地址留空启动，确认原 LLMWiki 页面和原有流程不变。
|
||
2. 在可信网络中放行 DeerFlow，配置地址，测试连接并创建个人库、上传文档、等待解析完成；确认 DeerFlow 请求没有认证头。
|
||
3. 普通用户直接发布，换另一用户确认能立即读取和检索、但不能修改；再由所有者取消公开并确认访问随即失效。
|
||
4. 给智能体绑定两个库，新建对话取消其中一个，确认引用只来自保留的库；重新打开对话确认选择恢复。
|
||
5. 撤销公共发布或删除用户权限后继续提问，确认工具实时拒绝已失效的知识库。
|