GBrain 入门指南：AI 知识库搭建筑梦

本指南记录 GBrain 的安装配置过程，以及从零开始使用的工作流。

---

一、安装部署

环境要求

• Node.js 18+
• Bun 或 Node.js 运行时
• MiniMax API Key（用于向量嵌入）

部署步骤

1. 克隆 GBrain

cd /Users/zyongzhu/Workbase
git clone <gbrain-repo> gbrain
cd gbrain

2. 配置 MiniMax 向量 GBrain 默认使用 OpenAI 格式，但 MiniMax API 参数不同，需要适配：

编辑 src/core/ai/recipes/minimax.ts，添加请求/响应转换函数 minimaxCompatFetch：

• 请求：将 input 转为 texts，添加 type: "db"
• 响应：将 vectors 转为 OpenAI 的 data.embedding 格式

编辑 src/cli.ts 的 buildGatewayConfig，添加：

if (c.minimax_api_key) envFromConfig.MINIMAX_API_KEY = c.minimax_api_key;

编辑 src/core/config.ts 的 GBrainConfig 接口，添加 minimax_api_key 字段。

3. 配置文件 在 ~/.gbrain/config.json 配置：

{
  "engine": "pglite",
  "database_path": "/Users/zyongzhu/.gbrain/brain.pglite",
  "embedding_model": "minimax:embo-01",
  "minimax_api_key": "你的APIKey"
}

启动并初始化

export MINIMAX_API_KEY="你的APIKey"
cd /Users/zyongzhu/Workbase/gbrain
bun run src/cli.ts init

---

二、导入知识库

首次导入

bun run src/cli.ts import /Users/zyongzhu/ThirdSpace/space

等待完成（约 5-10 分钟，取决于文档数量）。

查看状态

# 查看统计
bun run src/cli.ts stats

# 查看健康状态
bun run src/cli.ts health

---

三、日常使用流程

搜索与查询

关键词搜索（快速找文档）：

bun run src/cli.ts search "关键词"
bun run src/cli.ts search "知识图谱" --limit 10

混合搜索（AI 问答式，需要先启用 MINIMAX_API_KEY）：

export MINIMAX_API_KEY="你的APIKey"
bun run src/cli.ts query "我的笔记里关于控制理论的内容"
bun run src/cli.ts ask "我最近在学什么？"

同步更新

手动同步：

bun run src/cli.ts sync /Users/zyongzhu/ThirdSpace/space

自动同步（守护进程）：

# 安装定时同步
bun run src/cli.ts sync --install-cron

# 或持续监控
bun run src/cli.ts sync --watch

只刷新嵌入（文档变了但向量没更新）：

bun run src/cli.ts embed --stale

---

四、高级功能

知识图谱

查看链接：

# 查看某页面的 inbound links
bun run src/cli.ts backlinks <slug>

# 遍历链接图谱
bun run src/cli.ts graph <slug> --depth 2

# 创建实体关联
bun run src/cli.ts link <from_slug> <to_slug> --type related

自动维护

自动驾驶模式：

bun run src/cli.ts autopilot --install

孤独页面检测（找出没有任何连接的页面）：

bun run src/cli.ts orphans

代码索引（开发者）

# 索引代码
bun run src/cli.ts reindex-code

# 查找 symbol 定义
bun run src/cli.ts code-def "myFunction"

# 查找 symbol 引用
bun run src/cli.ts code-refs "myFunction"

---

五、MCP 服务（供 AI 调用）

如果希望其他 AI 工具（如 Claude Code）通过 MCP 调用 GBrain：

# STDIO 模式
bun run src/cli.ts serve

# HTTP 模式（可 OAuth）
bun run src/cli.ts serve --http --port 8080

---

六、故障排除

问题	解决
"insufficient balance"	MiniMax 余额不足，需要充值
"Invalid JSON response"	检查 minimaxCompatFetch 是否正确配置
导入后搜索无结果	确保设置了 MINIMAX_API_KEY 环境变量
嵌入dimension不匹配	运行 gbrain migrate --embedding-dimensions 1536

---

七、下一步建议

1. 今天：用 gbrain query 体验一次混合搜索
2. 本周：配置 sync --watch 或 autopilot 实现自动同步
3. 长期：建立页面间链接习惯，让知识图谱真正生长