sage-wiki配置教程

本教程记录了知识库自动化项目中 sage-wiki 配置的所有问题和调试过程。
包含失败尝试、根因分析和最终解决方案。
更新日期：2026-05-11

目录

1. 项目背景
2. 遇到的问题
3. 尝试过的方法（失败）
4. 根因分析
5. 最终解决方案
6. 正确配置示例
7. 验证方法
8. 服务器状态
9. 教训总结

1. 项目背景

目标

在腾讯云服务器（159.75.8.188）上部署 sage-wiki，实现微信文章、B站视频转录等内容的知识图谱构建。

原始环境

• 服务器：腾讯云 Ubuntu 22.04
• Ollama：已安装 v0.23.2
• Go：已安装 1.22.3
• sage-wiki：已安装
• API：最初使用 MiniMax

原始问题

服务器上 OpenClaw 接收的微信文章和 B站视频转录需要：

1. 自动存档
2. 生成知识图谱
3. 支持搜索和关联

2. 遇到的问题

问题 1：MiniMax API 429 限流

现象：

HTTP 429: Token Plan 主要面向个人开发者的交互式使用场景 当前请求量较高，请稍后重试

原因：MiniMax Token Plan 限制 RPM（每分钟请求数）

问题 2：embedding provider 不可用

现象：

level=WARN msg="no embedding provider available — vector search disabled" ⏳ Tier 1: Index + embed sources (311 items) Done: 0/311

原因：

• config.yaml 中embed.provider: openai-compatible和embed.model: emb-o1
• emb-o1 在 MiniMax API 端点不可用

问题 3：目录结构不匹配

现象：config.yaml 中 sources 路径与实际目录不符

原因：服务器 workspace 和本地 MyVault 是两套目录体系

问题 4：DeepSeek 不支持 Batch API

现象：

Error: compile: submit batch: openai batch: upload returned 404: 404 page not found

原因：DeepSeek/v1/batches端点不存在

问题 5：图片文件 embedding 失败

现象：

tier 1 embed: embedding failed path=微信文章/4月_图片/xxx.jpg error="embed: API returned 404"

原因：DeepSeek-v4-flash 不支持 image_url 格式

问题 6：Ollama nomic-embed-text 长度限制

现象：

error="embed: API returned 400: the input length exceeds the context length"

原因：

• nomic-embed-text 默认只有 2048 tokens 上下文
• 长文本（>1500字符）会触发限制

问题 7：服务器磁盘空间不足

现象：

no space left on device

原因：40G 磁盘已用 38G，可用仅剩 36M

3. 尝试过的方法（失败）

尝试 1：降低 max_parallel

配置：

compiler:max_parallel:1# 从 10 降到 1

结果：❌ 仍然触发 429 限流，只是变慢

尝试 2：切换到 DeepSeek API

配置：

api:provider:openai-compatibleapi_key:YOUR_DEEPSEEK_API_KEYbase_url:https://api.deepseek.com/v1

结果：❌ DeepSeek Batch API 返回 404

尝试 3：在 sources 下配置 chunk_size

配置：

sources:-path:微信文章type:articlechunk_size:500# ❌ 无效chunk_overlap:50

结果：❌ 不生效，文件仍然被整体发送

尝试 4：在 embed 下配置 chunk_size

配置：

embed:provider:openai-compatibleapi_key:ollamabase_url:http://localhost:11434/v1model:nomic-embed-textchunk_size:1000# ❌ 无效chunk_overlap:100

结果：❌ 不生效，日志仍显示完整文件发送

尝试 5：设置 batch_threshold: 99999

配置：

compiler:max_parallel:2batch_threshold:99999# ❌ 新版无效

结果：❌ 仍然使用 batch 模式

尝试 6：使用 emb-o1 embedding

配置：

embed:provider:openai-compatiblebase_url:https://api.minimaxi.com/anthropic/v1model:emb-o1

结果：❌ emb-o1 也有长度限制，且端点不可用

尝试 7：升级 Go 和 sage-wiki

命令：

goinstallgithub.com/xoai/sage-wiki/cmd/sage-wiki@latest

结果：❌ 磁盘空间不足，无法编译

尝试 8：忽略图片目录（配置位置错误）

配置：

ignore:-'*/5月_图片'-'*/4月_图片'-'*/3月_图片'

结果：❌ 图片仍然被处理（日志显示）

4. 根因分析

根因 1：chunk_size 配置位置错误

错误理解：以为 chunk_size 可以配置在 sources 或 embed 下

源码分析：

// Source 结构体中没有 chunk_size 字段 // EmbedConfig 结构体中也没有 chunk_size 字段 // chunk_size 必须配置在 search 下

正确位置：

search:chunk_size:1000# ✅ 正确位置

根因 2：batch 禁用方式错误

错误理解：以为用 batch_threshold: 99999 可以禁用

源码分析：

// 新版使用 compiler.mode 字段// mode: standard 禁用 batch// mode: batch 强制启用// mode: auto 自动选择

正确方式：

compiler:mode:standard# ✅ 禁用 batch

根因 3：nomic-embed-text 上下文限制

问题：

• 默认 nomic-embed-text 只有 2048 tokens 上下文
• 中文 1 token ≈ 1.5 字符
• 所以约 1500 字符就会超限

解决方案：创建自定义模型扩展到 8192 tokens

echo"FROM nomic-embed-text:v1.5 PARAMETER num_ctx 8192">Modelfile.nomic ollama create nomic-embed-text:8k-fModelfile.nomic

根因 4：ignore 配置语法问题

问题：

ignore:-'*/_图片/**'# ❌ 可能不生效-'*.jpg'# ❌ 可能不生效

正确方式：

ignore:-"*.jpg"-"*.png"-"*/_图片/**"-"*/_图片"

5. 最终解决方案

5.1 创建 nomic-embed-text:8k 模型

# 创建自定义 Modelfileecho"FROM nomic-embed-text:v1.5 PARAMETER num_ctx 8192">Modelfile.nomic# 构建模型ollama create nomic-embed-text:8k-fModelfile.nomic

5.2 升级 sage-wiki 到最新版本

# 清理磁盘空间sudojournalctl --vacuum-size=20Msudorm-rf/root/.cache# 克隆并编译gitclone https://github.com/xoai/sage-wiki.gitcdsage-wiki go build-osage-wiki ./cmd/sage-wikisudocpsage-wiki /root/go/bin/

5.3 正确配置 config.yaml

version:1project:myvault-wikisources:-path:微信文章type:articlewatch:false-path:bilibili_outputtype:articlewatch:false-path:transcriptstype:articlewatch:false-path:researchtype:articlewatch:falseoutput:wikiignore:-"*.jpg"-"*.jpeg"-"*.png"-"*.gif"-"*.webp"-"*.bmp"-"*/_图片/**"-"*/_图片"-".wiki"-"__pycache__"-".obsidian"-"temp"-"logs"api:provider:openai-compatibleapi_key:YOUR_DEEPSEEK_API_KEYbase_url:https://api.deepseek.com/v1models:summarize:deepseek-v4-flashextract:deepseek-v4-flashwrite:deepseek-v4-flashlint:deepseek-v4-flashquery:deepseek-v4-flashembed:provider:openai-compatibleapi_key:ollamabase_url:http://localhost:11434/v1model:nomic-embed-text:8ksearch:chunk_size:1000hybrid_weight_bm25:0.7hybrid_weight_vector:0.3default_limit:10compiler:max_parallel:2mode:standard

5.4 启动编译

# 停止现有编译sudopkill-f"sage-wiki compile"# 启动新编译cd/root/.openclaw/workspacenohup/root/go/bin/sage-wiki compile--project/root/.openclaw/workspace--fresh>/tmp/compile.log2>&1&

6. 正确配置示例

配置层级说明

config.yaml ├── sources[] # 源文件配置 │ ├── path # ✅ 可以配置 │ ├── type # ✅ 可以配置 │ ├── watch # ✅ 可以配置 │ └── chunk_size # ❌ 无效（不存在此字段） │ ├── output # 输出目录 │ ├── ignore[] # 忽略规则 │ ├── api{} # LLM API 配置 │ ├── models{} # 模型配置 │ ├── embed{} # embedding 配置 │ ├── provider # ✅ 可以配置 │ ├── base_url # ✅ 可以配置 │ ├── model # ✅ 可以配置 │ └── chunk_size # ❌ 无效（不存在此字段） │ ├── search{} # 搜索配置 │ ├── chunk_size # ✅ 正确位置！ │ └── ... │ └── compiler{} # 编译配置 ├── max_parallel ├── mode # standard/batch/auto └── batch_threshold # ❌ 新版已移除

关键配置对照表

7. 验证方法

7.1 验证编译是否正常

# 查看日志tail-f/tmp/compile.log# 检查进程psaux|grepsage-wiki

7.2 验证分块是否生效

观察日志中是否出现：

tier 1 chunk embed failed ... chunk=0 tier 1 chunk embed failed ... chunk=1/2 tier 1 chunk embed failed ... chunk=1/3

如果出现chunk=N（N>0），说明分块功能正在工作。

7.3 验证 output

ls-la/root/.openclaw/workspace/wiki/ls/root/.openclaw/workspace/wiki/concepts/ls/root/.openclaw/workspace/wiki/summaries/

7.4 验证 API

# 测试 Ollama embeddingcurl-s-XPOST http://localhost:11434/api/embeddings\-d'{"model":"nomic-embed-text","prompt":"test"}'# 测试长文本curl-s-XPOST http://localhost:11434/api/embeddings\-d'{"model":"nomic-embed-text:8k","prompt":"'"$(python-c'print("测试"*500))"'"}'

8. 服务器状态

当前状态（2026-05-11）

编译结果

错误分析

9 个错误主要来自：

1. 微信文章汇总文件（超长，132 chunks）
2. 部分 B站视频转录（2-3 chunks）
3. LLM 返回空摘要

这些错误可以接受，不影响核心功能。

9. 教训总结

教训 1：配置位置必须正确

错误：根据猜测配置参数位置

正确：查看源码确认配置结构

// 正确做法：查看 config.go 中实际的结构体定义typeSearchConfigstruct{ChunkSizeint`yaml:"chunk_size"`// ✅ 这里}

教训 2：先升级再调试

错误：用旧版本调试，参数名称已变更

正确：先确保是最新版本

# 始终使用最新版本goinstallgithub.com/xoai/sage-wiki/cmd/sage-wiki@latest

教训 3：磁盘空间要提前检查

错误：编译到一半才发现空间不足

正确：操作前检查并清理

df-h/sudojournalctl --vacuum-size=20M

教训 4：API 兼容性要实测

错误：以为 DeepSeek 兼容 OpenAI 协议就能用 Batch API

正确：每个端点都要单独测试

# 测试 Batch APIcurl-XPOST https://api.deepseek.com/v1/batches...# 返回 404 → 不支持

教训 5：文档可能过时

错误：参考旧文档配置

正确：查看源码或官方示例

# 查看最新配置示例gitclone https://github.com/xoai/sage-wiki.gitcatsage-wiki/README*.md

教训 6：模型限制要测试

错误：以为 embedding 模型没有长度限制

正确：实测确定边界

# 测试不同长度forlengthin[100,500,1000,1500,2000,3000]:test_embedding(length)# 发现 >1500 开始失败

附录：完整调试时间线

2026-05-10 上午 ├── 尝试降低 max_parallel → ❌ 仍然限流 ├── 切换到 DeepSeek API → ❌ Batch API 404 └── 切换 embed 到 ollama → ⚠️ 长度限制 2026-05-10 下午 ├── 尝试 sources 下 chunk_size → ❌ 不生效 ├── 尝试 embed 下 chunk_size → ❌ 不生效 ├── 添加图片到 ignore → ⚠️ 部分生效 └── 更新复盘文档 2026-05-11 上午 ├── 测试 nomic-embed-text 长度限制 │ ├── 1500字 ✅ 成功 │ ├── 2000字 ❌ 失败（返回空向量） │ └── 确认：~1500 字符限制 ├── 用户咨询专家 └── 获取正确配置方案 2026-05-11 下午 ├── 清理磁盘空间 ├── 升级 sage-wiki ├── 创建 nomic-embed-text:8k ├── 应用正确配置 └── 编译成功 ✅