1. 为什么纯向量检索撑不起一个「第二大脑」如果你正在给 Agent 设计长期记忆或者想给自己搭一个能记住「谁在哪家公司、谁投资了谁」的本地知识库那你大概率已经踩过同一个坑向量库能告诉你「这两段话意思像」但它永远答不出「Alice 工作的地方有谁投过钱」。这不是模型不够强而是检索范式本身的天花板。纯向量检索把每段文本压成一个高维点靠余弦相似度找邻居。它擅长语义模糊匹配比如「怎么配置数据库连接」能召回「数据库连接参数设置」。但一旦问题需要跨文档、跨实体做关系推理向量空间里那两个点可能离得很远于是直接漏召回。我拿一个最小例子说明这件事。下面这段代码用 sentence-transformers 做纯向量检索文档里明确写了「Bob 投资了 Acme 公司」但查询「Alice 工作的地方有谁投资」时它根本排不进 Top-2from sentence_transformers import SentenceTransformer import numpy as np model SentenceTransformer(BAAI/bge-small-zh-v1.5) documents [ Alice在Acme公司担任CTO, Acme公司是一家B轮金融科技公司, Alice和Bob上周一起参加了会议, Bob投资了Acme公司, ] doc_embeddings model.encode(documents) query Alice工作的地方有谁投资 query_embedding model.encode([query]) similarities np.dot(doc_embeddings, query_embedding[0]) print(向量检索Top-2:) for idx in np.argsort(similarities)[-2:][::-1]: print(f [{similarities[idx]:.3f}] {documents[idx]})实测下来排在最前面的是「Alice 和 Bob 上周一起参加了会议」和「Alice 在 Acme 公司担任 CTO」而真正包含答案的「Bob 投资了 Acme 公司」因为语义相似度低被挤出去了。问题出在哪「Bob 投资了 Acme 公司」和「Alice 工作的地方有谁投资」在字面和语义上都不像但它们在图谱上是相邻节点Alice —works_at→ Acme ←invests_in— Bob。向量检索看不到这条路径图谱检索可以。这就是 GBrain 要解决的核心问题。它把「向量 关键词 图谱」三种检索融合在一起导入文档时自动抽实体、建关系查询时三路召回再加权排序。官方给出的数据是加上知识图谱后检索准确率提升 31.4 个百分点这个量级已经不是调参能追上的而是范式差异。适合谁看这篇正在选型 Agent 记忆系统的工程师、想本地部署知识图谱的开发者、以及纠结 GBrain / OpenSPG / GraphRAG 到底选哪个的技术负责人。下面我会从架构拆到可复制的 docker-compose 和 schema再给三组验证动作最后做选型对比。2. TaoToken 前置给 GBrain 接一个稳定的模型出口GBrain 本身是检索和存储层但它的实体提取、关系抽取、以及最终答案生成都依赖 LLM。本地部署时最容易卡住的一步不是 bun 装不上而是模型 API 不通——要么 key 没配要么 base_url 写错要么模型 ID 对不上。我的做法是先把模型出口统一到 TaoToken它是一个兼容 OpenAI 与 Anthropic 协议的模型接入层好处是 GBrain 里所有需要 LLM 的地方都指向同一个 Base URL 和 Key换模型只改一个 Model ID不用动代码。官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。这里有个关键点GBrain 的实体抽取默认走 OpenAI 兼容接口所以你要准备三件套——Base URL、API Key、Model ID。Base URL 填https://taotoken.net/apiKey 在控制台生成Model ID 按你实际用的模型填。如果你用的是 Claude Code 这类 Anthropic 协议工具Base URL 要换成对应的 Anthropic 兼容地址这点在接入文档里有说明。我试过在 GBrain 的.env里这样配# .env OPENAI_API_KEYsk-你的taotoken密钥 OPENAI_BASE_URLhttps://taotoken.net/api GBRAIN_LLM_MODELgpt-4o-mini GBRAIN_EMBEDDING_MODELtext-embedding-3-small注意 embedding 模型和 LLM 模型可以分开配。GBrain 的向量索引维度必须和 embedding 模型一致比如text-embedding-3-small是 1536 维你后面在 schema 里写向量维度时就得对上否则导入时会报维度不匹配。为什么建议先做这一步因为 GBrain 的「睡眠整理」是定时任务它会周期性调用 LLM 做实体对齐和矛盾检测。如果模型出口不稳定整理任务会堆积最后表现为「导入很快但查询越来越慢」。把模型出口固定下来后面调检索权重时才有干净的基线。如果你还没生成 Key可以去 API Keys 页面创建路径是 https://taotoken.net/api-keys 。生成后建议先在模型对话里发一条测试消息确认 Key 和 Base URL 能通再往 GBrain 里填。这一步花两分钟能省掉后面半小时的 401 排查。3. 可复制配置docker-compose 图谱 schema 检索权重这一节是全文最该收藏的部分。我把 GBrain 本地部署拆成三块容器编排、图谱 schema、检索权重参数。每一块都能直接复制。先说 docker-compose。GBrain 官方推荐用 bun 直接跑但生产环境我更倾向容器化因为 Postgres 和向量扩展需要固定版本。下面这份配置把 GBrain 主服务、Postgres带 pgvector、以及一个可选的 Neo4j 图谱后端编排在一起# docker-compose.yml version: 3.9 services: gbrain: image: ghcr.io/garrytan/gbrain:latest container_name: gbrain ports: - 8787:8787 environment: - GBRAIN_DB_URLpostgres://gbrain:gbrainpostgres:5432/gbrain - GBRAIN_GRAPH_BACKENDneo4j - GBRAIN_NEO4J_URIbolt://neo4j:7687 - GBRAIN_NEO4J_USERneo4j - GBRAIN_NEO4J_PASSWORDgbrain123 - OPENAI_API_KEY${OPENAI_API_KEY} - OPENAI_BASE_URLhttps://taotoken.net/api - GBRAIN_LLM_MODELgpt-4o-mini - GBRAIN_TOKENIZERjieba volumes: - ./notes:/data/notes - ./gbrain-data:/root/.gbrain depends_on: postgres: condition: service_healthy neo4j: condition: service_healthy restart: unless-stopped postgres: image: pgvector/pgvector:pg16 container_name: gbrain-postgres environment: - POSTGRES_USERgbrain - POSTGRES_PASSWORDgbrain - POSTGRES_DBgbrain volumes: - ./pg-data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U gbrain] interval: 5s timeout: 3s retries: 10 restart: unless-stopped neo4j: image: neo4j:5.20 container_name: gbrain-neo4j environment: - NEO4J_AUTHneo4j/gbrain123 - NEO4J_PLUGINS[apoc] ports: - 7474:7474 - 7687:7687 volumes: - ./neo4j-data:/data healthcheck: test: [CMD-SHELL, wget -qO- http://localhost:7474 || exit 1] interval: 10s timeout: 5s retries: 10 restart: unless-stopped这份配置里有两个容易忽略的点。第一GBRAIN_TOKENIZERjieba必须显式打开否则中文实体抽取会退化成按空格切词召回率直接掉一半。第二Neo4j 的 healthcheck 用的是 HTTP 端口 7474不是 bolt 端口 7687写错了容器会一直等不到健康状态。接着是图谱 schema。GBrain 默认用「unknown」类型存所有实体查询时没法按类型过滤。我建议在config.yaml里显式定义实体类型和关系类型# config.yaml graph: backend: neo4j entity_types: - Person - Organization - Project - Document - Concept relation_types: - works_at - invests_in - mentions - authored_by - related_to extraction: model: gpt-4o-mini temperature: 0 max_entities_per_doc: 30 min_confidence: 0.6 retrieval: weights: vector: 0.4 keyword: 0.3 graph: 0.3 top_k: 5 pre_fetch_multiplier: 2 graph_hops: 2 fusion: weighted_sum tokenizer: name: jieba user_dict: ./dict/company_terms.txtgraph_hops: 2是关系推理的深度。设成 1 只能查到直接邻居设成 2 能查到「Alice 的同事的投资者」这种两跳关系。但别设太大超过 3 跳召回会爆炸延迟也上去了。检索权重这块vector: 0.4 / keyword: 0.3 / graph: 0.3是通用起点。如果你的场景以关系查询为主比如「谁和谁有合作」把 graph 提到 0.5如果以精确术语查询为主比如查某个 API 名把 keyword 提到 0.4。pre_fetch_multiplier: 2的意思是每路先召回 top_k 的两倍再融合避免某一路结果不够。最后是 MCP 接入配置让 Claude 或 Cursor 能直接调 GBrain{ mcpServers: { gbrain: { command: docker, args: [exec, -i, gbrain, gbrain, mcp-server, --memory, /root/.gbrain], env: { GBRAIN_API_KEY: your-gbrain-key } } } }注意这里command用的是docker exec因为 GBrain 跑在容器里。如果你是本机 bun 安装直接写gbrain加mcp-server参数即可。三件套Base URL、Key、Model ID在容器环境变量里已经配好MCP 这层只需要 GBrain 自己的 API Key。4. 验证请求三组动作确认检索真的生效配置写完不算完得用数据验证。我设计了三个动作分别验证实体召回、混合检索增益、以及图谱后端切换后的延迟变化。第一组导入样例文档检查实体召回率。准备一个sample.md内容包含多实体多关系# 项目周会记录 Alice 是 Acme 公司的 CTO负责支付网关项目。 Bob 是红杉资本的投资人2026 年 3 月投资了 Acme 公司。 Carol 在 Acme 公司担任支付网关的技术负责人向 Alice 汇报。 Acme 公司正在和 Beta 银行洽谈合作。导入命令docker exec -it gbrain gbrain import /data/notes/sample.md --verbose导入后查图谱docker exec -it gbrain gbrain graph query MATCH (n) RETURN n.name, n.type LIMIT 20预期能看到 Alice、Bob、Carol、Acme 公司、红杉资本、Beta 银行、支付网关项目这些实体且类型分别是 Person、Organization、Project。如果实体类型全是 unknown说明 schema 没加载检查config.yaml路径是否挂载进容器。第二组对比纯向量与混合检索的 Top-K 命中差异。用同一个查询跑两次一次关图谱一次开图谱# 纯向量 docker exec -it gbrain gbrain think Alice工作的地方有谁投资 --no-graph --top-k 3 # 混合检索 docker exec -it gbrain gbrain think Alice工作的地方有谁投资 --top-k 3纯向量模式下返回的大概率是「Alice 是 Acme 公司的 CTO」和「Carol 向 Alice 汇报」因为这两句和查询语义最接近。混合检索模式下图谱那一路会通过 Alice → Acme 公司 → Bob 这条路径把「Bob 投资了 Acme 公司」召回融合后它应该进 Top-3。如果没进把graph权重从 0.3 提到 0.5 再试。第三组切换 GraphRAG 后端观察响应延迟。GBrain 支持把图谱后端从 Neo4j 换成 GraphRAG 的社区检测模式。改config.yamlgraph: backend: graphrag graphrag: community_level: 2 llm_model: gpt-4o-mini重启后跑同一个查询用time记录延迟time docker exec -it gbrain gbrain think Acme公司的投资方是谁 --top-k 3实测下来Neo4j 后端因为走的是索引查询延迟通常在 200-400msGraphRAG 后端要做社区摘要匹配首次查询可能到 1.5-2s但全局性问题比如「这个知识库主要讲了什么」它的回答质量更高。所以选型不是谁替代谁而是按查询类型分流。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth部署 GBrain 时我踩过的坑基本集中在四类报错这里逐个对照。401 Unauthorized。最常见的原因是.env里的OPENAI_API_KEY没传进容器。docker-compose 里写的是${OPENAI_API_KEY}它从宿主机环境变量读如果你只在.env文件里写了但没export容器里就是空的。解决方式是在 docker-compose 同级目录放.env并确认 compose 会自动加载或者直接在environment里写死 Key不推荐但排查时可用。另一个原因是 Base URL 写成了https://taotoken.net少了/api请求打到了首页而不是 API 端点也会返回 401。local proxy failed。这个报错通常出现在容器内访问外部 API 时。GBrain 容器默认走宿主机网络出口如果你宿主机上配了什么本地转发工具容器里不一定继承。排查方式是进容器手动 curl 一下docker exec -it gbrain curl -I https://taotoken.net/api如果容器内不通而宿主机通说明是网络命名空间隔离问题给容器加network_mode: host或显式配 DNS 即可。注意别在容器里配任何非官方的转发配置直接用平台提供的标准 API 地址最稳。reading choices 报错。这个一般出现在 LLM 返回格式不符合预期时。GBrain 的实体抽取期望模型返回结构化 JSON如果你用的模型不支持 JSON mode或者 temperature 设太高返回里混了自然语言解析就会报reading choices之类的错。解决方式是在config.yaml里把extraction.temperature设成 0并确认 Model ID 支持 JSON 输出。如果换模型后还报去模型对话里手动发一条同样的 prompt看返回结构对不对。OAuth 相关报错。如果你接的是 Anthropic 协议的模型GBrain 可能走 OAuth 流程而不是 API Key。这时候要确认三件套里的 Base URL 用的是 Anthropic 兼容地址Key 类型也对。OAuth 报错常见的是 token 过期或 scope 不足重新在控制台生成一次 Key 通常能解决。如果用的是 Claude Code 接入注意它的配置文件和 GBrain 的.env是两套别混用。排查顺序建议先gbrain doctor看整体健康再按报错关键词定位。401 查 Key 和 Base URLlocal proxy failed 查容器网络reading choices 查模型输出格式OAuth 查协议和 Key 类型。这四类覆盖了 90% 的部署失败场景。6. 选型与接入把 GBrain 放进你的 Agent 技术栈GBrain、OpenSPG、GraphRAG 这三个经常被放在一起比但它们其实不在同一个生态位。GBrain 的定位是个人和团队的第二大脑特点是轻、自动、一体化。导入即建图不需要你手写 schemaMCP 生态也成熟接 Claude 和 Cursor 很顺。缺点是实体识别精度是 demo 级中文分词要手动配 jieba数据量级到十万页就吃力。OpenSPG 是企业级知识图谱引擎强在 schema 约束和可审计。金融、医疗这类需要合规和权限隔离的场景OpenSPG 的 Schema 定义和推理规则是刚需。代价是部署重、配置多不适合个人快速上手。GraphRAG 是文档级知识图谱加 RAG强在社区检测和全局摘要。问「这批文档主要讲了什么」这类全局问题GraphRAG 的回答质量最高。但全程 LLM 驱动成本和延迟都高适合千级文档的问答场景。我的选型建议是个人知识管理直接 GBrain企业结构化知识建模用 OpenSPG文档问答加知识发现用 GraphRAGAgent 长期记忆用 GBrain 加 OpenSPG 混合GBrain 做语义检索层OpenSPG 做结构化事实存储两者通过 MCP 协议连接。接入路径上如果你要长期跑编码 Agent 或做 Agent 记忆系统建议走 Coding Plan把模型出口和检索层都固定下来路径是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果只是先验证模型能不能通去模型对话发一条消息最快地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各协议的 Base URL 对照表。最后说一个我踩过的坑GBrain 的「睡眠整理」定时任务默认每小时跑一次实体合并如果你导入的文档量大第一次整理可能跑很久期间查询会变慢。建议首次导入后手动触发一次整理并观察日志确认没有任务堆积再交给定时调度。整理任务和查询共用同一个模型出口所以前面把 TaoToken 配稳这件事在这里会直接体现为整理任务不卡顿。