Hermes 智能体+Dify 知识库详细部署过程

本手册覆盖从零开始的完整流程：Docker 安装 → Dify 部署 → 模型配置 → 知识库搭建 → Hermes 对接。

预计耗时：2-3 小时（不含模型下载时间）。

一、环境要求
[二、安装 Docker](#二、安装 Docker)
[三、部署 Dify](#三、部署 Dify)
四、配置模型
五、搭建知识库
[六、创建知识库 API Key](#六、创建知识库 API Key)
[七、配置 Hermes 对接 Dify](#七、配置 Hermes 对接 Dify)
八、验证与使用
九、运维管理
[附录 A：常见问题](#附录 A：常见问题)
[附录 B：关键文件清单](#附录 B：关键文件清单)

一、环境要求

项目	最低要求	推荐
操作系统	Ubuntu 22.04 / 24.04 LTS	Ubuntu 24.04 LTS
内存	8 GB	16 GB
磁盘	20 GB 可用	50 GB 可用
CPU	2 核	4 核+

前提条件：

有 sudo 权限的普通用户账号
本机或局域网内已有一台 LLM 大模型服务
Hermes Agent 已安装并正常运行

本手册示例环境：

操作系统：Ubuntu 24.04 LTS
Hermes 安装路径：~/.hermes/hermes-agent/

二、安装 Docker

2.1 卸载旧版 Docker（如有）

bash 复制代码

# 停止服务
sudo systemctl stop docker docker.socket 2>/dev/null

# 卸载所有 docker 相关包
sudo apt-get purge -y docker.io docker-compose docker-doc docker-ce docker-ce-cli containerd 2>/dev/null
sudo apt-get autoremove -y --purge

# 清理残留数据
sudo rm -rf /var/lib/docker /var/lib/containerd /etc/docker
sudo groupdel docker 2>/dev/null

2.2 安装 Docker

如果服务器能访问 Docker Hub 官方镜像仓库，可以用官方安装脚本。

如果 Docker Hub 访问不畅，可以用 apt 方式安装。

方式 A：apt 安装（推荐）

bash 复制代码

sudo apt-get update
sudo apt-get install -y docker.io docker-compose-v2

方式 B：官方脚本安装（需要能访问 Docker Hub）

bash 复制代码

curl -fsSL https://get.docker.com | sh

2.3 配置镜像源

为提升镜像拉取效率，建议配置国内镜像源。

bash 复制代码

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
    "填写国内镜像源地址（网上搜一下）"
  ]
}
EOF

2.4 启动 Docker 并设置开机自启

bash 复制代码

sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl enable docker

2.5 验证安装

bash 复制代码

# 检查版本
docker --version
# 预期输出: Docker version 29.x.x

docker compose version
# 预期输出: Docker Compose version v2.x.x

# 检查服务状态
sudo systemctl is-active docker
# 预期输出: active

# 测试镜像拉取（验证镜像源是否生效）
docker pull hello-world
docker run --rm hello-world
# 预期输出: Hello from Docker!

三、部署 Dify

3.1 获取 Dify 代码

Dify 官方仓库在 GitHub。你也可以使用 Gitee 上的镜像仓库。

方式 A：从 Gitee 克隆（推荐，速度快）

bash 复制代码

cd ~
git clone https://gitee.com/xxx（能用的dify镜像）

方式 B：从 GitHub 克隆

bash 复制代码

cd ~
git clone https://github.com/langgenius/dify.git

3.2 配置 Dify 环境变量

bash 复制代码

cd ~/dify/docker
cp .env.example .env

默认配置即可正常启动，关键默认值：

配置项	默认值	说明
`EXPOSE_NGINX_PORT`	80	Dify Web 访问端口
`DB_PASSWORD`	difyai123456	PostgreSQL 密码
`REDIS_PASSWORD`	difyai123456	Redis 密码

如果 80 端口被占用，可修改端口：

bash 复制代码

# 编辑 .env，找到 EXPOSE_NGINX_PORT 改为其他端口，如 3000
# EXPOSE_NGINX_PORT=3000

3.3 启动 Dify

bash 复制代码

cd ~/dify/docker
docker compose up -d

首次启动会拉取所有镜像，根据镜像源和下载速度可能需要 10-30 分钟。

共 12 个容器，启动完成后检查状态：

bash 复制代码

docker compose ps

预期输出（所有容器状态为 Up）：

复制代码

NAME                      IMAGE                                    STATUS
docker-api-1              langgenius/dify-api:1.x.x                Up (healthy)
docker-api_websocket-1    langgenius/dify-api:1.x.x                Up
docker-worker-1           langgenius/dify-api:1.x.x                Up
docker-worker_beat-1      langgenius/dify-api:1.x.x                Up
docker-web-1              langgenius/dify-web:1.x.x                Up
docker-nginx-1            nginx:latest                             Up
docker-db_postgres-1      postgres:15-alpine                       Up (healthy)
docker-redis-1            redis:6-alpine                           Up (healthy)
docker-weaviate-1         semitechnologies/weaviate:1.27.0         Up
docker-sandbox-1          langgenius/dify-sandbox:0.2.x            Up (healthy)
docker-ssrf_proxy-1       ubuntu/squid:latest                      Up
docker-plugin_daemon-1    langgenius/dify-plugin-daemon:0.x.x      Up

3.4 验证部署

bash 复制代码

# 本地验证
curl -s http://localhost | head -5

# 浏览器访问
# http://<服务器IP>
# 例如: http://10.xx.xx.xx

首次访问会进入初始化页面，设置管理员账号和密码。

3.5 常用管理命令

bash 复制代码

cd ~/dify/docker

# 查看容器状态
docker compose ps

# 查看日志
docker compose logs -f api        # 查看 API 日志
docker compose logs -f worker     # 查看 Worker 日志

# 重启
docker compose restart

# 停止
docker compose down

# 启动
docker compose up -d

# 更新 Dify 版本
cd ~/dify
git pull origin main
cd docker
docker compose pull
docker compose up -d

四、配置模型

Dify 本身不包含大模型，需要对接外部模型服务。请确保您能正常访问相关的模型服务。

4.1 模型说明

模型类型	作用	是否必须	示例
LLM（大语言模型）	理解问题、生成回答	是（Dify 应用需要）	qwen2.5:7b, deepseek-r1:7b
Text Embedding（文本嵌入）	文档和问题转向量，用于语义检索	是（知识库必须）	bge-m3, nomic-embed-text
Rerank（重排序）	对检索结果重新排序，提升准确率	推荐	bge-reranker-v2-m3

注意： 本手册的架构中，Hermes 作为智能体使用自己的 LLM，Dify 仅作为外部知识库。

因此 Dify 中必须配置 Embedding 模型（知识库索引用），推荐配置 Rerank 模型（提升检索准确率）。

Dify 中的 LLM 可选配置------如果你也在 Dify 中创建应用则需要。

4.2 在 Dify 中配置模型

浏览器访问 Dify：http://<服务器IP>
用管理员账号登录
点击右上角头像 → 设置 → 模型供应商
根据你的模型来源选择对应的供应商：

如果使用 Ollama（本地模型）：

a. 在 Ollama 所在机器上安装模型：

bash 复制代码

# 在模型服务器上执行
ollama pull bge-m3                    # Embedding 模型
ollama pull bge-reranker-v2-m3        # Rerank 模型
# ollama pull qwen2.5:7b              # LLM 模型（可选）

b. 确保 Ollama 监听在 0.0.0.0（允许远程访问）：

bash 复制代码

# 编辑 Ollama 服务配置
sudo systemctl edit ollama
# 添加:
# [Service]
# Environment="OLLAMA_HOST=0.0.0.0:11434"
sudo systemctl restart ollama

c. 在 Dify 中添加 Ollama 供应商：

供应商列表中找到 Ollama
点击 添加模型
填写 Ollama 服务地址：http://<模型服务器IP>:11434
模型名称：bge-m3，模型类型选 Text Embedding
再添加 bge-reranker-v2-m3，模型类型选 Rerank
（可选）添加 qwen2.5:7b，模型类型选 LLM

如果使用商业 API（如 OpenAI / 智谱 / 通义千问）：

在模型供应商页面找到对应供应商
填入 API Key
选择需要的模型

4.3 验证模型配置

配置完成后，在 Dify 设置页面能看到已添加的模型列表，状态为"可用"。

五、搭建知识库

5.1 创建知识库

登录 Dify Web 界面
点击顶部导航栏的 知识库
点击 创建知识库
上传文档（支持 PDF、Word、TXT、Markdown、CSV 等格式）

5.2 配置索引方式

创建知识库时需要选择索引方式：

索引方式	说明	推荐
高质量索引	使用 Embedding 模型生成向量，支持语义检索	推荐
经济索引	仅关键词匹配，不需要 Embedding 模型	文档量大且无 Embedding 模型时

选择"高质量索引"时的检索设置：

检索模式	说明	推荐
混合检索	语义 + 关键词，覆盖最全	推荐
语义检索	纯向量匹配	术语精确的场景
全文检索	纯关键词匹配	不推荐

推荐配置：

索引方式：高质量索引
检索模式：混合检索
Top K：5（返回最相关的 5 个片段）
Rerank 模型：bge-reranker-v2-m3
Rerank 模式：按重排序分数

5.3 等待索引完成

上传文档后，Dify 会自动进行文本分段和向量化。在知识库文档列表中，您可以看到每个文档的索引状态：

处理中 --- 正在分段和向量化
已完成 --- 可以检索
错误 --- 检查模型配置是否正确

5.4 测试知识库

进入知识库详情页
点击 召回测试 标签
输入测试问题，例如"数据库运维安全有哪些风险"
查看检索结果，确认返回的文档片段是否相关

六、创建知识库 API Key

Hermes 通过 Dify 的 Knowledge Base API 调用知识库，需要创建专用的 API Key。

6.1 通过 Dify Web 界面创建（推荐）

登录 Dify Web 界面
进入知识库列表页面
点击右侧 API 按钮（或在知识库详情页点击 API）
点击 创建 API 密钥
复制生成的 API Key（格式为 dataset-xxxxxxxxxxxxxxxxxxxxxxxx）

重要： API Key 只在创建时显示一次，请立即保存。

6.2 通过数据库创建（备用方案）

如果 Web 界面无法创建（如权限限制），可以直接在数据库中创建：

bash 复制代码

# 1. 查找租户 ID
docker exec docker-db_postgres-1 psql -U postgres -d dify \
  -c "SELECT id, name FROM tenants LIMIT 5;"

# 2. 查找知识库 ID
docker exec docker-db_postgres-1 psql -U postgres -d dify \
  -c "SELECT id, name FROM datasets LIMIT 5;"

# 3. 生成 API Key（替换 <TENANT_ID> 为实际租户 ID）
API_TOKEN="dataset-$(python3 -c "import secrets, string; print(''.join(secrets.choice(string.ascii_letters + string.digits) for _ in range(24)))")"
TOKEN_ID=$(python3 -c "import uuid; print(uuid.uuid4())")
TENANT_ID="<你的租户ID>"

docker exec docker-db_postgres-1 psql -U postgres -d dify \
  -c "INSERT INTO api_tokens (id, tenant_id, type, token, created_at) VALUES ('${TOKEN_ID}', '${TENANT_ID}', 'dataset', '${API_TOKEN}', NOW());"

echo "API Key: ${API_TOKEN}"

6.3 验证 API Key

bash 复制代码

# 替换 <DATASET_ID> 和 <API_KEY>
curl -X POST "http://localhost/v1/datasets/<DATASET_ID>/retrieve" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "测试查询",
    "retrieval_model": {
      "search_method": "hybrid_search",
      "top_k": 3,
      "score_threshold_enabled": false,
      "reranking_enable": false
    }
  }'

如果返回包含 records 数组的 JSON，则 API Key 有效。

6.4 记录关键信息

完成本章后，记录以下三个值，后续配置 Hermes 时需要：

复制代码

Dify 地址:       http://<服务器IP>           例如 http://10.xx.xx.xx
知识库 API Key:  dataset-xxxxxxxxxxxxxxxxxxxx 
知识库 ID:       xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

七、配置 Hermes 对接 Dify

7.1 创建 Dify 知识库工具

在 Hermes 的 tools 目录下创建工具文件：

bash 复制代码

cat > ~/.hermes/hermes-agent/tools/dify_knowledge_tool.py << 'TOOL_EOF'
#!/usr/bin/env python3
"""
Dify Knowledge Base Tool

Queries a Dify knowledge base (dataset) via the external API to retrieve
relevant document chunks. Used by Hermes as an external knowledge source.
"""

import json
import logging
import os
import urllib.request
import urllib.error

logger = logging.getLogger(__name__)

DIFY_BASE_URL = os.getenv("DIFY_BASE_URL", "http://localhost").rstrip("/")
DIFY_API_KEY = os.getenv("DIFY_API_KEY", "")
DIFY_DATASET_ID = os.getenv("DIFY_DATASET_ID", "")

MAX_CONTENT_CHARS = 2000
MAX_RESPONSE_CHARS = 8000


def _check_config() -> bool:
    return bool(DIFY_API_KEY and DIFY_DATASET_ID)


def dify_knowledge_search(
    query: str,
    top_k: int = 5,
    search_method: str = "hybrid_search",
    score_threshold: float = 0.0,
    reranking_enable: bool = True,
) -> str:
    """Search the Dify knowledge base for relevant chunks."""
    if not _check_config():
        return json.dumps({
            "error": "Dify knowledge base not configured. Set DIFY_API_KEY and DIFY_DATASET_ID in .env",
        }, ensure_ascii=False)

    top_k = max(1, min(10, top_k))

    payload = {
        "query": query,
        "retrieval_model": {
            "search_method": search_method,
            "top_k": top_k,
            "score_threshold_enabled": score_threshold > 0,
            "score_threshold": score_threshold,
            "reranking_enable": reranking_enable,
        },
    }

    url = f"{DIFY_BASE_URL}/v1/datasets/{DIFY_DATASET_ID}/retrieve"
    headers = {
        "Authorization": f"Bearer {DIFY_API_KEY}",
        "Content-Type": "application/json",
    }

    try:
        req = urllib.request.Request(
            url,
            data=json.dumps(payload).encode("utf-8"),
            headers=headers,
            method="POST",
        )
        with urllib.request.urlopen(req, timeout=30) as resp:
            data = json.loads(resp.read().decode("utf-8"))
    except urllib.error.HTTPError as e:
        body = e.read().decode("utf-8", errors="replace")
        return json.dumps({
            "error": f"Dify API HTTP {e.code}",
            "detail": body[:500],
        }, ensure_ascii=False)
    except Exception as e:
        return json.dumps({
            "error": f"Dify API request failed: {str(e)}",
        }, ensure_ascii=False)

    records = data.get("records", [])
    if not records:
        return json.dumps({
            "query": query,
            "results": [],
            "message": "No relevant chunks found in knowledge base.",
        }, ensure_ascii=False)

    results = []
    total_chars = 0
    for r in records:
        segment = r.get("segment", {})
        content = segment.get("content", "")
        doc_info = segment.get("document", {})
        score = r.get("score", 0)

        if len(content) > MAX_CONTENT_CHARS:
            content = content[:MAX_CONTENT_CHARS] + "..."

        entry = {
            "content": content,
            "score": round(score, 4),
            "document": doc_info.get("name", "unknown"),
            "position": segment.get("position", 0),
        }
        results.append(entry)
        total_chars += len(content)

        if total_chars >= MAX_RESPONSE_CHARS:
            break

    return json.dumps({
        "query": query,
        "total_found": len(records),
        "returned": len(results),
        "results": results,
    }, ensure_ascii=False)


# ---------------------------------------------------------------------------
# Registry
# ---------------------------------------------------------------------------
from tools.registry import registry

DIFY_KNOWLEDGE_SCHEMA = {
    "name": "dify_knowledge_search",
    "description": (
        "Search the Dify knowledge base for relevant document chunks. "
        "Use this tool when you need domain-specific knowledge, product documentation, "
        "or contextual information from the knowledge base. "
        "Returns ranked text chunks with relevance scores."
    ),
    "parameters": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "The search query --- what you want to find in the knowledge base.",
            },
            "top_k": {
                "type": "integer",
                "description": "Maximum number of chunks to return (1-10). Default 5.",
                "minimum": 1,
                "maximum": 10,
                "default": 5,
            },
            "search_method": {
                "type": "string",
                "description": "Search method: 'hybrid_search' (default, recommended), 'semantic_search', or 'full_text_search'.",
                "enum": ["hybrid_search", "semantic_search", "full_text_search"],
                "default": "hybrid_search",
            },
            "score_threshold": {
                "type": "number",
                "description": "Minimum relevance score 0.0-1.0. 0 = return all results. Default 0.",
                "minimum": 0,
                "maximum": 1,
                "default": 0,
            },
        },
        "required": ["query"],
    },
}

registry.register(
    name="dify_knowledge_search",
    toolset="web",
    schema=DIFY_KNOWLEDGE_SCHEMA,
    handler=lambda args, **kw: dify_knowledge_search(
        query=args.get("query", ""),
        top_k=args.get("top_k", 5),
        search_method=args.get("search_method", "hybrid_search"),
        score_threshold=args.get("score_threshold", 0.0),
        reranking_enable=True,
    ),
    check_fn=_check_config,
    requires_env=["DIFY_API_KEY", "DIFY_DATASET_ID"],
    emoji="📚",
    max_result_size_chars=100_000,
)
TOOL_EOF

7.2 配置环境变量

编辑 Hermes 的环境变量文件 ~/.hermes/.env，在文件末尾添加：

bash 复制代码

# Dify Knowledge Base
DIFY_BASE_URL=http://localhost
DIFY_API_KEY=dataset-xxxxxxxxxxxxxxxxxxxxxxxx
DIFY_DATASET_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

替换为实际值：

变量	说明	示例值
`DIFY_BASE_URL`	Dify 访问地址	`http://10.xx.xx.xx` 或 `http://localhost`
`DIFY_API_KEY`	知识库 API Key	`实际key`
`DIFY_DATASET_ID`	知识库 ID	`实际ID`

如果 Hermes 和 Dify 部署在同一台服务器，使用 http://localhost 即可。

如果部署在不同服务器，请使用 Dify 服务器的实际访问地址。。

7.3 注册工具到 toolsets.py

编辑 ~/.hermes/hermes-agent/toolsets.py，在所有包含 web_search 的行中追加 dify_knowledge_search：

找到这一行（会出现多次，每处都改）：

python 复制代码

    "web_search", "web_extract",

改为：

python 复制代码

    "web_search", "web_extract", "dify_knowledge_search",

使用 sed 命令批量替换：：

bash 复制代码

sed -i 's/"web_search", "web_extract",/"web_search", "web_extract", "dify_knowledge_search",/g' ~/.hermes/hermes-agent/toolsets.py

7.4 重启 Hermes

bash 复制代码

# 如果在 CLI 交互界面中，退出后重新启动
hermes

八、验证与使用用

8.1 验证工具加载

启动 Hermes 后，在对话中输入：

复制代码

帮我从知识库搜索一下xxx

Hermes 应自动调用 dify_knowledge_search 工具，返回知识库中的相关内容。

8.2 故障排查

如果工具调用失败，请按以下步骤检查：：

Dify 服务是否正常：
bash 复制代码
```
curl -s http://localhost | head -5
```

API Key 是否有效：

bash 复制代码

curl -X POST "http://localhost/v1/datasets/<DATASET_ID>/retrieve" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","retrieval_model":{"search_method":"hybrid_search","top_k":1,"score_threshold_enabled":false,"reranking_enable":false}}'

环境变量是否加载：
bash 复制代码
```
grep DIFY ~/.hermes/.env
```

工具文件是否存在：

bash 复制代码

ls -la ~/.hermes/hermes-agent/tools/dify_knowledge_tool.py

九、运维管理

9.1 Dify 日常管理

bash 复制代码

cd ~/dify/docker

# 查看容器状态
docker compose ps

# 查看实时日志
docker compose logs -f

# 重启某个服务
docker compose restart api

# 停止所有服务
docker compose down

# 启动所有服务
docker compose up -d

# 查看资源占用
docker stats

9.2 更新 Dify

bash 复制代码

cd ~/dify
git pull origin main
cd docker
docker compose pull
docker compose up -d

9.3 备份与恢复

备份数据库和知识库数据：

bash 复制代码

# 创建备份目录
mkdir -p ~/dify-backup

# 备份 PostgreSQL 数据库
docker exec docker-db_postgres-1 pg_dump -U postgres dify > ~/dify-backup/dify_db_$(date +%Y%m%d).sql

# 备份 Weaviate 向量数据
docker cp docker-weaviate-1:/var/lib/weaviate ~/dify-backup/weaviate_$(date +%Y%m%d)

# 备份上传文件
cp -r ~/dify/docker/volumes/app/storage ~/dify-backup/storage_$(date +%Y%m%d)

恢复数据：

bash 复制代码

# 恢复数据库
docker exec -i docker-db_postgres-1 psql -U postgres -d dify < ~/dify-backup/dify_db_YYYYMMDD.sql

9.4 新增知识库 API Key

如果需要为其他系统创建 API Key：

bash 复制代码

# 通过 Dify Web 界面：知识库 → API → 创建 API 密钥
# 或通过数据库创建（参考第六章 6.2 节）

附录 A：常见问题

A1. Docker 拉取镜像超时

现象： docker compose up -d 时镜像拉取失败或超时

解决：

确认 Docker 网络连通性：docker info；
如果一直失败，可配置镜像加速器（参考 2.3 节）
手动测试拉取：
bash 复制代码
```
docker pull langgenius/dify-api:1.15.0
```
如果仍然失败，检查防火墙和代理设置

A2. Dify 启动后无法访问

现象： 浏览器访问 http://<IP> 无响应

排查步骤：

检查容器状态：docker compose ps，确认 nginx 容器为 Up
检查端口占用：sudo ss -tlnp | grep :80
检查防火墙：sudo ufw status，确保 80 端口开放
本地测试：curl http://localhost
查看日志：docker compose logs nginx

A3. 知识库索引失败

现象： 上传文档后状态为"错误"

排查步骤：

检查 Embedding 模型是否配置正确
在 Dify 设置 → 模型供应商中确认模型状态为"可用"
查看 Worker 日志：docker compose logs worker
确认 Ollama 服务正常：curl http://<Ollama服务器IP>:11434/api/tags

A4. Hermes 调用知识库返回 401

现象： dify_knowledge_search 返回 HTTP 401

原因： API Key 无效或过期

解决：

重新生成 API Key（Dify Web → 知识库 → API）
更新 ~/.hermes/.env 中的 DIFY_API_KEY
重启 Hermes

A5. Hermes 调用知识库返回 404

现象： dify_knowledge_search 返回 HTTP 404

原因： 知识库 ID 错误

解决：

查询正确的知识库 ID：

bash 复制代码

docker exec docker-db_postgres-1 psql -U postgres -d dify \
  -c "SELECT id, name FROM datasets;"

更新 ~/.hermes/.env 中的 DIFY_DATASET_ID
重启 Hermes

A6. 检索结果不相关

优化建议：

使用"混合检索"模式而非"全文检索"
开启 Rerank 模型
调整 Top K 参数（3-5 通常最佳）
优化文档分段策略（在知识库设置中调整 chunk size）
确认 Embedding 模型支持中文（推荐 bge-m3）

附录 B：关键文件清单

文件路径	说明
`/etc/docker/daemon.json`	Docker 镜像加速器配置
`~/dify/`	Dify 代码仓库
`~/dify/docker/docker-compose.yaml`	Dify Docker Compose 编排文件
`~/dify/docker/.env`	Dify 环境配置
`~/.hermes/.env`	Hermes 环境变量（含 Dify 连接配置）
`~/.hermes/hermes-agent/tools/dify_knowledge_tool.py`	Hermes Dify 知识库工具
`~/.hermes/hermes-agent/toolsets.py`	Hermes 工具集配置

附录 C：架构图

复制代码

┌─────────────────────────────────────────────────────┐
│                    用户                               │
│                      │                               │
│                      ▼                               │
│            ┌──────────────────┐                      │
│            │   Hermes Agent   │                      │
│            │   (智能体/CLI)    │                      │
│            └────────┬─────────┘                      │
│                     │                                │
│         dify_knowledge_search                        │
│         (HTTP API 调用)                              │
│                     │                                │
│                     ▼                                │
│  ┌──────────────────────────────────────┐            │
│  │         Dify 平台 (Docker)            │            │
│  │  ┌─────────┐  ┌──────────┐           │            │
│  │  │  Nginx  │→│   API    │           │            │
│  │  └─────────┘  └────┬─────┘           │            │
│  │                     │                 │            │
│  │  ┌─────────────────▼──────────┐      │            │
│  │  │    知识库 (Weaviate)        │      │            │
│  │  │    向量检索 + Rerank       │      │            │
│  │  └────────────────────────────┘      │            │
│  └──────────────────────────────────────┘            │
│                        │                             │
│                        ▼                             │
│  ┌──────────────────────────────────────┐            │
│  │    模型服务 (Ollama / 远程 API)       │            │
│  │  bge-m3 (Embedding)                  │            │
│  │  bge-reranker-v2-m3 (Rerank)         │            │
│  └──────────────────────────────────────┘            │
└─────────────────────────────────────────────────────┘

数据流说明：

用户向 Hermes 提问
Hermes 调用 dify_knowledge_search 工具，将问题发送到 Dify API
Dify 用 Embedding 模型将问题转向量
Weaviate 向量数据库检索最相关的文档片段
Rerank 模型对结果重排序
Dify 返回排序后的文档片段给 Hermes
Hermes 结合知识库内容和自身 LLM 能力生成回答

本手册基于以下版本验证通过：

操作系统: Ubuntu 24.04 LTS
Docker: 29.1.3
Docker Compose: v2.40.3
Dify: 1.15.0
Weaviate: 1.27.0
PostgreSQL: 15-alpine
Redis: 6-alpine

文档编写日期: 2026-07-03