企业官网建设流程全解析

1. 为什么我把 GraphRAG 的 Key 全塞进了 TaoToken

GraphRAG 是把传统 RAG 从「向量相似度」升级成「图结构检索」的一套玩法：它先用大模型从你的文本里抽取实体和关系，写进图数据库，再在问答时沿着实体路径去找上下文。Neo4j 负责存这张图，TRAE 负责零代码编排，三者拼起来就是一条本地知识库的可视化链路。适合谁？适合手上有几十上百篇文档、想让模型「按关系回答」而不是「按段落拼凑」的人，也适合不想写太多胶水代码、想用 IDE 侧栏对话就把流程跑通的人。

但这条链路有个特别烦人的地方：GraphRAG 抽实体要调模型，Neo4j 写入要连数据库，TRAE 编排又要读配置，每个环节都伸手要 Key。我一开始就是阿里云百炼一个 Key、智谱一个 Key、本地又写死一个，结果换个模型就要改三处代码，.env、settings.json、config.toml各存一份，改漏一个就报 401。后来我把所有模型调用统一收敛到 TaoToken 一个 Key 上，配置只维护一份，链路才真正跑顺。

这篇就按「原问题 → TaoToken 前置 → 可复制配置 → 验证请求 → 错排查 → CTA」的顺序，把 GraphRAG + Neo4j + TRAE 这条本地知识图谱可视化链路讲清楚。你跟着做，能拿到一份能直接用的settings.json和config.toml骨架、一份 Neo4j 连接参数模板，以及一次从图谱写入到可视化验证的完整动作。

2. TaoToken 前置：一个 Key 管住整条链路

TaoToken 在这里扮演的角色，是「模型调用的统一入口」。GraphRAG 抽实体、生成回答，底层都是 OpenAI 兼容的 chat/completions 接口，TaoToken 提供的就是这个兼容层，所以你不用为每个模型供应商单独维护一套鉴权逻辑。官网在 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 入口是 https://taotoken.net/api ，注意 API 地址不带 UTM 参数，配置里填这个就行。

你需要提前准备两样东西：一个 TaoToken 的 API Key，以及一个能用的模型名。Key 在控制台的 API Keys 页面创建，地址是 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite 。创建完复制出来，形如sk-开头的一串字符，后面所有配置都复用它。

注意：Key 只存在本地.env或环境变量里，别写进会提交到 Git 的代码。我习惯在项目根目录放.env，然后.gitignore里加一行.env。

模型名这块，GraphRAG 抽实体对模型的指令遵循能力有要求，建议选一个稳定的对话模型。你可以在模型对话页面先试一下连通性，地址是 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，随便问一句「你好」，能正常返回就说明 Key 和模型名都对。如果你后面要长期跑编码和 Agent 类的批量任务，可以看下 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，按套餐走比单次调用省心。

3. 可复制配置：settings.json 与 config.toml 骨架

GraphRAG 官方工程用settings.yaml，但很多人（包括我）会把它转成settings.json或config.toml来统一管理，因为 TRAE 侧栏读配置时 JSON/TOML 更好解析。下面给两份骨架，你按自己项目路径改。

3.1 settings.json 骨架

这份配置的核心是把api_base指向 TaoToken，api_key从环境变量读，避免硬编码。

{ "llm": { "api_base": "https://taotoken.net/api", "api_key": "${TAOTOKEN_API_KEY}", "model": "gpt-4o-mini", "max_tokens": 4096, "temperature": 0.1, "request_timeout": 120 }, "embeddings": { "api_base": "https://taotoken.net/api", "api_key": "${TAOTOKEN_API_KEY}", "model": "text-embedding-3-small" }, "graphrag": { "root_dir": "./graph", "input_dir": "./graph/input", "chunk_size": 1000, "chunk_overlap": 200, "entity_types": ["人物", "地点", "事件", "组织"] }, "neo4j": { "uri": "bolt://localhost:7687", "username": "neo4j", "password": "${NEO4J_PASSWORD}", "database": "neo4j" } }

chunk_size和chunk_overlap这两个参数直接决定抽实体的粒度和 Token 消耗。1000/200 是我实测下来比较平衡的值：块太小实体关系断裂，块太大一次请求 Token 飙升。entity_types建议按你的语料定制，比如做《红楼梦》就写人物、地点、事件，做技术文档就写模块、接口、依赖。

3.2 config.toml 骨架

如果你更习惯 TOML，等价配置如下，TRAE 侧栏解析 TOML 也没问题。

[llm] api_base = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}" model = "gpt-4o-mini" max_tokens = 4096 temperature = 0.1 request_timeout = 120 [embeddings] api_base = "https://taotoken.net/api" api_key = "${TAOTOKEN_API_KEY}" model = "text-embedding-3-small" [graphrag] root_dir = "./graph" input_dir = "./graph/input" chunk_size = 1000 chunk_overlap = 200 entity_types = ["人物", "地点", "事件", "组织"] [neo4j] uri = "bolt://localhost:7687" username = "neo4j" password = "${NEO4J_PASSWORD}" database = "neo4j"

3.3 Neo4j 连接参数模板

Neo4j 这块单独拎出来，因为连接串写错是最常见的坑。本地 Community Server 默认监听 7687（Bolt 协议）和 7474（HTTP 浏览器界面）。

# .env 文件，放在项目根目录 TAOTOKEN_API_KEY=sk-你的TaoToken密钥 NEO4J_URI=bolt://localhost:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=password123 NEO4J_DATABASE=neo4j

注意：NEO4J_URI用bolt://而不是http://，Python 驱动走的是 Bolt 协议。浏览器里访问可视化界面才用http://localhost:7474，两者别混。

4. 验证请求：从图谱写入到可视化

配置齐了，接下来跑一次完整动作。整个过程分三步：装依赖、抽实体写图、浏览器验证。

4.1 装依赖

在 TRAE 的终端里执行：

pip install neo4j langchain langchain-community langchain-openai pip install neo4j-graphrag pip install sentence-transformers pip install python-dotenv

neo4j-graphrag是官方封装的图谱 RAG 库，python-dotenv用来读.env。装完在项目里能看到site-packages多出对应目录。

4.2 抽实体并写入 Neo4j

准备一个build_graph.py，核心逻辑是读文本、分块、调 TaoToken 抽实体关系、写 Neo4j。

import os from dotenv import load_dotenv from neo4j import GraphDatabase from openai import OpenAI load_dotenv() client = OpenAI( api_key=os.getenv("TAOTOKEN_API_KEY"), base_url="https://taotoken.net/api" ) driver = GraphDatabase.driver( os.getenv("NEO4J_URI"), auth=(os.getenv("NEO4J_USERNAME"), os.getenv("NEO4J_PASSWORD")) ) def extract_entities(text): resp = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "从文本中抽取实体和关系，输出JSON数组，每项含source、relation、target。"}, {"role": "user", "content": text} ], temperature=0.1 ) return resp.choices[0].message.content def write_to_neo4j(tx, source, relation, target): tx.run( "MERGE (a:Entity {name: $source}) " "MERGE (b:Entity {name: $target}) " "MERGE (a)-[:REL {type: $relation}]->(b)", source=source, relation=relation, target=target ) with open("./graph/input/reddream.txt", "r", encoding="utf-8") as f: raw = f.read() chunks = [raw[i:i+1000] for i in range(0, len(raw), 800)] with driver.session() as session: for chunk in chunks[:5]: result = extract_entities(chunk) print(result)

这里我故意只跑前 5 个 chunk，因为整本书抽完 Token 消耗很大。你先用小样本验证链路通不通，通了再放开。

4.3 浏览器可视化验证

打开http://localhost:7474，用neo4j/password123登录，在查询框输入：

MATCH (a:Entity)-[r:REL]->(b:Entity) RETURN a, r, b LIMIT 50

如果前面写入成功，你会看到节点和关系以图的形式铺开，人物之间连着带REL标签的边。这一步就是「可视化链路跑通」的标志。如果图是空的，说明写入没成功，回到 4.2 看终端有没有报错。

5. 本篇常见错排查

5.1 401 Unauthorized

最常见。九成是TAOTOKEN_API_KEY没读到，或者.env没被load_dotenv()加载。先在终端echo $TAOTOKEN_API_KEY确认环境变量有值，再确认.env和脚本在同一目录。还有一种情况是 Key 复制时带了空格，sk-后面别留空。

5.2 Neo4j 连接被拒

报ServiceUnavailable: Failed to establish connection，先确认 Neo4j 服务在跑。Windows 下看服务列表，macOS/Linux 用neo4j status。再确认端口：Bolt 是 7687，如果你改过配置，.env里的 URI 要同步改。密码错会报AuthError，默认密码password123只在首次登录有效，改过就用新的。

5.3 抽实体返回不是 JSON

模型有时会输出带解释的文字，导致json.loads失败。两个办法：一是把temperature压到 0.1 以下，二是在 system prompt 里强调「只输出 JSON，不要任何解释」。我试过在 prompt 末尾加一句「输出必须是合法 JSON 数组」，成功率明显提升。

5.4 Token 消耗过快

整本书抽实体，免费额度很容易见底。对策是先用单章测试，确认抽取质量后再决定要不要全量跑。另外chunk_overlap别设太大，200 已经够保持上下文，设成 500 会让每个块重复内容变多，Token 翻倍。

5.5 TRAE 侧栏读不到配置

TRAE 读settings.json时，如果 JSON 里有注释或尾逗号会解析失败。用编辑器格式化一遍，确保是严格 JSON。TOML 相对宽松，但${VAR}这种占位符需要你的代码里手动替换，TRAE 不会自动展开环境变量。

6. 把 Key 收敛之后，链路才真正可维护

走到这里，你应该已经跑通了「文本 → 抽实体 → 写 Neo4j → 浏览器可视化」这条链路。回头看，真正让这条链路从「能跑一次」变成「能反复跑」的，不是某个模型多强，而是把分散的 Key 收敛成了一个。以前换模型要改三处配置，现在只改settings.json里的model字段，api_base和api_key纹丝不动。

如果你后面要把这套东西接到编码或 Agent 流程里，比如让 TRAE 自动读图谱、自动补全代码上下文，可以走 Coding Plan，地址是 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有 OpenAI 兼容接口的完整参数说明，遇到字段对不上时翻一下比猜快。Key 管理还是回到 https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite ，需要轮换或加额度都在那操作。

最后留一个我踩过的坑：Neo4j 的MERGE语句在并发写入时可能产生重复节点，如果你发现图里同一个人物出现两次，把MERGE (a:Entity {name: $source})改成先CREATE CONSTRAINT给name加唯一约束，再跑写入就不会重了。这个约束加在build_graph.py开头执行一次即可，后面所有写入都受益。