ARTICLE DETAIL

资讯详情

深耕网站建设与运营推广的一线实战洞察。

graphify 导出链路实战:Wiki、Neo4j/FalkorDB、SVG/GraphML 与 MCP 服务及 Token 缩减基准

graphify 导出链路实战:Wiki、Neo4j/FalkorDB、SVG/GraphML 与 MCP 服务及 Token 缩减基准 graphify 导出链路实战Wiki、Neo4j/FalkorDB、SVG/GraphML 与 MCP 服务及 Token 缩减基准【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphifygraphify 在完成 AST 抽取、社区聚类和标注之后真正让知识图谱走出去的环节是导出export体系。本文以 graphify 的技能参考文档 exports.md 为主线逐条拆解其中的 7 个导出分支--wiki、--neo4j、--neo4j-push、--falkordb、--falkordb-push、--svg、--graphml、--mcp和 Token 缩减基准测试并结合 graphify/export.py、graphify/exporters/graphdb.py、graphify/cli.py 等源码说明每个命令的实际行为、默认值与工程细节如幂等 MERGE、密码环境变量、Cypher 注入防护帮助你在 Agent 工作流中正确配置和运行这些导出步骤。一、导出步骤的触发模型每个步骤只响应自己的 Flag参考文档开头明确了加载时机当用户命令中携带任一导出 Flag--wiki、--neo4j、--neo4j-push、--falkordb、--falkordb-push、--svg、--graphml、--mcp时加载该参考或者当语料规模大到值得跑 Token 缩减基准时加载。每个导出步骤只为自己的 Flag 执行未传 Flag 的步骤一律跳过。对应到 CLI 实现graphify/cli.py 中cmd export分支约 L2624校验子命令白名单Usage: graphify export format html [--graph PATH] [--labels PATH] [--node-limit N] [--no-viz] obsidian [--graph PATH] [--labels PATH] [--dir PATH] wiki [--graph PATH] [--labels PATH] svg [--graph PATH] [--labels PATH] graphml [--graph PATH] neo4j [--graph PATH] [--push URI] [--user U] [--password P] (or set NEO4J_PASSWORD instead of --password to keep it off argv) falkordb [--graph PATH] [--push URI] [--user U] [--password P] (or set FALKORDB_PASSWORD instead of --password to keep it off argv)几个值得注意的实现细节默认路径--graph默认读graphify-out/graph.json--labels默认读graphify-out/.graphify_labels.json社区标签。密码不落 argv源码注释标注了 F-031 设计——优先读取环境变量NEO4J_PASSWORD/FALKORDB_PASSWORD避免密码出现在ps输出和 shell 历史里显式--password仍然优先覆盖环境变量。--push要求密码neo4j --push时若密码未提供会直接报错退出graphify/cli.py L2904-L2908FalkorDB 的 push 则允许无凭据连接。下文按参考文档的步骤编号Step 6b / 7 / 7a / 7b / 7c / 7d / 8逐一展开。二、Step 6bWiki 导出仅当传入 --wiki参考文档要求只在原始命令显式带了--wiki时执行并且要在 Step 9清理之前运行因为清理会删掉.graphify_labels.json而 Wiki 导出依赖社区标签文件graphify export wiki从源码看graphify/cli.py 的subcmd wiki分支约 L2874有两个前置校验社区数据缺失即拒绝.graphify_analysis.json缺失或为空时直接报错退出提示先运行graphify extract .重建社区数据防止导出空 Wiki造成数据损失假象God Nodes 兜底分析文件中没有 god node 数据时调用 graphify/analyze.py 的god_nodes(G)现场计算。最终调用 graphify/wiki.py 的to_wiki()产出结构为每个社区一篇_COMMUNITY_*.md概览文章、每个 god node 一篇文章外加wiki/index.md作为 Agent 的入口页。运行成功时输出形如Wiki: N articles written to graphify-out/wiki/ graphify-out/wiki/index.md - agent entry pointWiki 中的社区标签是 LLM 生成非确定性的因此--labels显式指定标签文件是保证输出稳定的关键。三、Step 7Neo4j 导出--neo4j / --neo4j-push3.1 生成 Cypher 文件--neo4jgraphify export neo4j产出graphify-out/cypher.txt用于手动批量导入。CLI 输出的提示即导入方式cypher.txt written - import with: cypher-shell graphify-out/cypher.txt生成逻辑在 graphify/export.py 的to_cypher()L474-L498每个节点输出一行MERGE (n:FileType {id: ..., label: ...});节点 Label 取自节点的file_type首字母大写每条边输出一行MATCH ... MERGE (a)-[:RELATION {confidence: ...}]-(b);关系类型取边的relation大写形式并保留confidence属性EXTRACTED / INFERRED / AMBIGUOUS。安全性上_cypher_escape()与_cypher_label()graphify/export.py L429-L471做了双层防护字符串值转义反斜杠、单引号和换行防止突破cypher-shell的按行分句边界对应 F-008标识符位置Label、关系类型无法转义只能白名单化——剔除非[A-Za-z0-9_]字符不合法时回退到Entity/RELATES_TO。3.2 直推运行中的实例--neo4j-push urigraphify export neo4j --push bolt://localhost:7687 --user neo4j --password PASSWORD默认 URI 为bolt://localhost:7687默认用户neo4j凭据未提供时应向用户询问推荐用NEO4J_PASSWORD环境变量代替--password。推送实现在 graphify/exporters/graphdb.py 的push_to_neo4j()L9-L78通过官方 Python 驱动pip install neo4j逐节点、逐边执行参数化CypherMERGE (n:{FileType} {id: $id}) SET n $props MATCH (a {id: $src}), (b {id: $tgt}) MERGE (a)-[r:{REL}]-(b) SET r $props这里正是参考文档所说Uses MERGE - safe to re-run without creating duplicates的落地节点和边都是 upsert 语义重复推送不会产生重复数据。属性只保留str/int/float/bool标量且排除下划线前缀的内部键节点还会带上所属community编号。完成后打印Pushed to Neo4j: N nodes, M edges。四、Step 7aFalkorDB 导出--falkordb / --falkordb-push4.1 生成 Cypher 文件--falkordbgraphify export falkordb语句同样是 OpenCypher但 CLI 明确给出取舍建议FalkorDB 的GRAPH.QUERY逐条执行语句没有 Neo4jcypher-shell那样的批量脚本导入通道因此装图优先用--falkordb-push只在需要可移植的cypher.txt产物时才用文件形式cypher.txt written (graphify-out/cypher.txt) - statements are OpenCypher. FalkorDBs GRAPH.QUERY runs one statement at a time (no bulk script import), so load a graph with: graphify export falkordb --push falkordb://localhost:63794.2 直推实例--falkordb-push urigraphify export falkordb --push falkordb://localhost:6379默认 URIfalkordb://localhost:6379scheme 仅是信息性的——redis://或裸host:port都可以源码 graphify/exporters/graphdb.py 的push_to_falkordb()L80-L173里urlparse只取 host/port缺省端口 6379认证可选FalkorDB 默认无凭据运行凭据只在实例要求认证时才需要目标图名默认为graphify通过db.select_graph(graphify)选中同样使用 MERGE可重复执行不产生重复。从源码还可以确认一个细节URI 中内嵌的凭据优先于--user/--password参数无密码时不发送用户名避免 FalkorDB 把 Neo4j 风格的默认用户名当作未知 ACL 用户拒绝。五、Step 7b / 7cSVG 与 GraphML 导出graphify export svggraphify export graphmlSVGgraphify/export.pyto_svg()L1282 起基于 matplotlibAgg 后端spring_layout固定seed42布局可复现深色背景#1a1a2e节点大小按度数缩放社区颜色与 HTML 输出共用同一调色板EXTRACTED 置信度边画实线、其余画虚线并降低透明度有社区标签时自动带图例。产出graphify-out/graph.svgCLI 提示其可直接嵌入 Obsidian、Notion、GitHub README 等任意 Markdown 渲染环境无 JavaScript 依赖。matplotlib 缺失时会给出pip install matplotlib的提示。GraphMLto_graphml()L1205 起产出graphify-out/graph.graphml可用 Gephi、yEd 等任何 GraphML 兼容工具打开。实现上有几处工程化处理社区 ID 作为节点属性写入Gephi 可据此着色边保留confidence属性内部标记_origin、_src/_tgt等被剥离不泄漏到导出文件None转空串、非标量dict/list转 JSON 字符串规避 networkx 对非标量属性值的限制XML 非法控制字符被清除原子写先写临时文件再os.replace避免中途失败留下 0 字节的.graphml被下游误认为完整导出。六、Step 7dMCP 服务--mcp——把图谱变成可查询工具$(cat graphify-out/.graphify_python) -m graphify.serve graphify-out/graph.json这会启动一个stdio MCP 服务器把图谱包装成 7 个工具供外部 Agent 实时查询。graphify/serve.py 中注册的工具名L1617-L1681正是工具作用query_graph按自然语言问题检索图谱返回相关节点/边上下文get_node解析并查看单个节点详情get_neighbors列出节点的邻居及边属性get_community查看社区概览Community N — Name 头格式god_nodes返回度数最高的枢纽节点默认 top 10graph_stats图的整体统计信息shortest_path计算两节点间最短路径有向/无向自动选择把该服务接入 Claude Desktop 或任意 MCP 兼容的 Agent 编排器后其他 Agent 就能活地查询这张图。参考文档特别指出两个常见坑及解法Claude Desktop 不执行$(...)命令替换若 graphify 通过uv tool install安装系统python3无法 import graphify。因此command必须填cat graphify-out/.graphify_python打印出的绝对解释器路径{ mcpServers: { graphify: { command: absolute path from: cat graphify-out/.graphify_python, args: [-m, graphify.serve, /absolute/path/to/graphify-out/graph.json] } } }实现层面graphify/serve.py 的_load_graph()对输入做了防御强制.json后缀、执行文件大小上限检查、兼容links/edges两种键名并对旧版节点 ID 方案输出升级提示——这些保证 MCP 服务加载graph.json时不会因损坏文件或超大文件崩溃。服务端还维护一个带 LRU 的项目上下文缓存GRAPHIFY_MAX_CONTEXTS默认 8、最小 1支持多图谱场景下的并发查询。七、Step 8Token 缩减基准仅当 total_words 5000参考文档的判定条件是读取graphify-out/.graphify_detect.json中的total_words大于 5000 才运行基准 5000时静默跳过——小语料上图谱的价值是结构性清晰而非 Token 压缩。graphify benchmark运行时把输出直接贴到对话中。CLI 侧graphify/cli.pycmd benchmark分支L2931 起会先做文件大小上限检查再从.graphify_detect.json读取corpus_words传入基准函数读取失败则退回 graphify/benchmark.py 中的估算每节点约 50 词。graphify/benchmark.py 的测量方法透明可复核基线corpus_tokens corpus_words × 100 / 75即 100 词 ≈ 133 tokens 的朴素全量塞入方案图谱侧对 5 个内置示例问题如 how does authentication work分别做查询——按标签匹配选出 top 3 起始节点、BFS 展开 3 层子图把NODE .../EDGE ...行按每 4 字符 1 token 估算输出语料总 Token、节点/边数、平均查询成本、缩减倍数reduction_ratio以及每个问题各自的[Nx]缩减明细。输出报告形如graphify token reduction benchmark -------------------------------------------------- Corpus: 12,000 words - ~16,000 tokens (naive) Graph: 340 nodes, 812 edges Avg query cost: ~420 tokens Reduction: 38.1x fewer tokens per query Per question: [41.2x] how does authentication work ...若 5 个示例问题都匹配不到节点基准返回 Build the graph first 错误提示先建图。八、小结Flag 与命令的完整对照参考文档步骤触发 Flag命令产物/行为幂等性/注意Step 6b--wikigraphify export wikigraphify-out/wiki/含index.md依赖.graphify_labels.json与社区数据须在清理前运行Step 7--neo4jgraphify export neo4jgraphify-out/cypher.txt用cypher-shell批量导入Step 7--neo4j-pushgraphify export neo4j --push bolt://localhost:7687 --user neo4j --password PASSWORD直推 Neo4jMERGE 幂等密码建议走NEO4J_PASSWORDStep 7a--falkordbgraphify export falkordbgraphify-out/cypher.txtOpenCypher逐条执行装图建议改用 pushStep 7a--falkordb-pushgraphify export falkordb --push falkordb://localhost:6379直推 FalkorDB默认图名graphifyMERGE 幂等认证可选Step 7b--svggraphify export svggraphify-out/graph.svg需 matplotlibseed42 布局可复现Step 7c--graphmlgraphify export graphmlgraphify-out/graph.graphml原子写属性非标量安全化Step 7d--mcp$(cat graphify-out/.graphify_python) -m graphify.serve graphify-out/graph.jsonstdio MCP 服务7 个查询工具Claude Desktop 需绝对解释器路径Step 8total_words 5000graphify benchmarkToken 缩减报告小语料静默跳过掌握以上内容后你可以按语料规模和下游工具链Obsidian/Neo4j/FalkorDB/MCP 客户端组合选择导出分支所有命令都以graphify-out/下的graph.json为唯一输入源导出分支之间相互独立任一失败不影响其他产物而 MERGE 幂等、原子写与参数化查询等实现细节则保证了重复运行和增量重建场景下的数据安全。【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表