【开源发布】MermaidTrace: 让你的 Python 代码逻辑“看“得见！

玄同 765

大语言模型 (LLM) 开发工程师 | 中国传媒大学 · 数字媒体技术（智能交互与游戏设计）

ZEEKLOG · 个人主页 | GitHub · Follow

关于作者

• 深耕领域：大语言模型开发 / RAG 知识库 / AI Agent 落地 / 模型微调
• 技术栈：Python | RAG (LangChain / Dify + Milvus) | FastAPI + Docker
• 工程能力：专注模型工程化部署、知识库构建与优化，擅长全流程解决方案

「让 AI 交互更智能，让技术落地更高效」
欢迎技术探讨与项目合作，解锁大模型与智能交互的无限可能！

玄同 765

大语言模型 (LLM) 开发工程师 | 中国传媒大学 · 数字媒体技术（智能交互与游戏设计）

ZEEKLOG · 个人主页 | GitHub · Follow

关于作者

• 深耕领域：大语言模型开发 / RAG 知识库 / AI Agent 落地 / 模型微调
• 技术栈：Python | RAG (LangChain / Dify + Milvus) | FastAPI + Docker
• 工程能力：专注模型工程化部署、知识库构建与优化，擅长全流程解决方案

「让 AI 交互更智能，让技术落地更高效」
欢迎技术探讨与项目合作，解锁大模型与智能交互的无限可能！

【开源发布】MermaidTrace: 让你的 Python 代码逻辑"看"得见

让复杂的调用链一目了然。一行代码，将复杂的执行逻辑转化为清晰的 Mermaid 时序图。

当你在凌晨两点调试递归调用时

你接手了一个遗留项目，代码结构复杂，函数层层嵌套。你打开日志文件，看到的是这样的输出：

[INFO] Entering process_order [INFO] Entering validate_user [INFO] Entering check_permission [INFO] Exiting check_permission [INFO] Entering get_user_info [INFO] Exiting get_user_info [INFO] Exiting validate_user [INFO] Entering create_order ... 

几百行日志，你试图在脑海中拼凑出调用关系。半小时后，你放弃了，决定手动画一个时序图。又过了两小时，图画好了——但第二天代码改了，图又过时了。

这不是假设，这是很多开发者的日常。MermaidTrace 的出现改变了这一切：只需添加一个装饰器，代码执行时就会自动生成时序图。

添加装饰器

运行代码

自动生成时序图

实时预览

MermaidTrace 是什么？

MermaidTrace 是一个专门的日志工具，它能自动从代码执行中生成 Mermaid 时序图。它特别适合：

• 可视化复杂业务逻辑
• 理解微服务交互流程
• 调试递归和异步代码
• 自动生成技术文档

可视化结果

处理过程

你的代码

Python 函数

装饰器拦截

记录调用事件

构建调用链

生成 Mermaid 语法

时序图

交互式预览

核心价值

传统的日志是线性的文本，你需要阅读、理解、在脑海中重建调用关系。MermaidTrace 把这个过程自动化了——日志变成了图。

强大的 Web 预览界面

MermaidTrace 内置了一个功能强大的 Web 预览服务器，让你可以直观地查看生成的时序图：

主要特性：

• 实时预览：代码运行后，浏览器自动刷新，图表即时更新
• 多文件支持：可以同时管理多个 .mmd 文件
• 缩放平移：支持鼠标滚轮缩放和拖拽平移
• 一键导出：支持将图表导出为 SVG 格式
• 响应式布局：完美适配各种屏幕尺寸
• 完全离线：无需网络连接，静态资源本地化

快速上手：三步开始

1. 安装

pip install mermaid-trace 

2. 添加装饰器

from mermaid_trace import trace, trace_class @trace_classclassOrderService:"""订单服务类"""defprocess_order(self, order_id:int)->dict:"""处理订单""" self.validate_order(order_id)return self.create_order(order_id)defvalidate_order(self, order_id:int)->bool:"""验证订单"""return order_id >0defcreate_order(self, order_id:int)->dict:"""创建订单"""return{"order_id": order_id,"status":"created"}# 运行代码 service = OrderService() result = service.process_order(123)

3. 查看时序图

mermaid-trace serve flow.mmd 

这会启动一个本地服务器，自动打开浏览器，展示生成的时序图：

在 LLM 应用中的实践

场景一：可视化 RAG 检索流程

RAG 系统的检索流程往往涉及多个步骤：查询改写、向量检索、重排序、上下文构建。用 MermaidTrace 可以清晰展示整个流程。

from mermaid_trace import trace from typing import List @traceclassRAGPipeline:"""RAG 检索管道"""def__init__(self): self.retriever = VectorRetriever() self.reranker = Reranker() self.context_builder = ContextBuilder()asyncdefquery(self, question:str)->dict:# 查询改写 refined_query =await self.refine_query(question)# 向量检索 documents =await self.retriever.search(refined_query)# 重排序 ranked_docs =await self.reranker.rerank(documents, question)# 构建上下文 context = self.context_builder.build(ranked_docs)return{"query": question,"context": context}

生成的时序图清晰展示了 RAG 的完整流程：

ContextBuilderRerankerVectorRetrieverRAGPipelinemainContextBuilderRerankerVectorRetrieverRAGPipelinemainqueryrefine_querysearch[doc_0, doc_1, ...]rerank[doc_0, doc_1, doc_2]buildcontext stringresult

场景二：追踪 LangChain Agent 执行

LangChain 的 Agent 执行流程复杂，涉及工具调用、决策循环、错误处理。MermaidTrace 可以帮你理解每一步发生了什么。

from mermaid_trace import trace_class @trace_classclassLLMAgent:"""LLM Agent"""def__init__(self): self.tools ={"search": self.search,"calculator": self.calculator}asyncdefrun(self, query:str)->str:for i inrange(3): action =await self.decide(query)if action["type"]=="finish":return action["answer"] result =await self.tools[action["tool"]](action["input"])return"完成"

生成的时序图清晰展示了 Agent 的决策循环：

calculatorsearchLLMAgentmaincalculatorsearchLLMAgentmainrundecide{tool: search}search结果decide{tool: calculator}calculator结果decide{type: finish}最终答案

场景三：调试 FastAPI 异步流程

FastAPI 的异步处理流程难以追踪，MermaidTrace 可以帮你理解请求的完整生命周期。

from fastapi import FastAPI, Depends from mermaid_trace import trace app = FastAPI()@traceclassDatabaseService:asyncdefget_user(self, user_id:int)->dict:return{"id": user_id,"name":f"User{user_id}"}asyncdefget_orders(self, user_id:int)->list:return[{"id": i}for i inrange(3)]@app.get("/users/{user_id}")asyncdefget_user(user_id:int, db: DatabaseService = Depends(get_db)): user, orders =await asyncio.gather( db.get_user(user_id), db.get_orders(user_id))return{"user": user,"orders": orders}

核心装饰器详解

@trace - 函数级追踪

from mermaid_trace import trace @tracedefprocess_data(data:str)->str:return data.upper()

@trace_class - 类级追踪

from mermaid_trace import trace_class @trace_classclassMyService:defmethod_a(self):pass

@trace_interaction - 交互追踪

from mermaid_trace import trace_interaction @trace_interactionasyncdefcomplex_operation(): result =await step_one()returnawait step_two(result)

CLI 工具

MermaidTrace 提供了内置的 CLI 工具，支持热重载和实时预览：

# 预览单个文件 mermaid-trace serve flow.mmd # 预览目录 mermaid-trace serve ./diagrams # 指定端口 mermaid-trace serve flow.mmd --port3000# 不自动打开浏览器 mermaid-trace serve flow.mmd --no-browser # 查看版本 mermaid-trace version 

代码变更

自动重新运行

生成新时序图

浏览器自动刷新

v0.7.1 新特性：

• ✅ 完全离线支持：无需网络连接即可使用
• ✅ 简化安装：只需 pip install mermaid-trace

与 LangChain 的集成

MermaidTrace 提供了 LangChain 的专用处理器：

from mermaid_trace.integrations.langchain import MermaidTraceCallbackHandler handler = MermaidTraceCallbackHandler()# 附加到 LangChain 执行 chain = LLMChain(llm=llm, prompt=prompt) result = chain.run("你好", callbacks=[handler])# 自动生成 LangChain 执行时序图

性能考虑

MermaidTrace 设计为低开销：

生产环境建议：

import os from mermaid_trace import set_enabled # 根据环境变量控制 set_enabled(os.getenv("ENABLE_TRACE","false").lower()=="true")

总结

MermaidTrace 的核心理念是：日志不应该是文本，而应该是图。在 LLM 应用开发中，当执行流程越来越复杂时，可视化比阅读日志更高效。

一行装饰器，让你的代码自己"画"出执行流程。

参考资料

• GitHub: xt765/mermaid-trace
• Gitee: xt765/mermaid-trace
• PyPI: mermaid-trace
• 在线体验: Colab Demo

如果你觉得这个工具有所帮助，请在 GitHub 上给我一个 ⭐️ Star！