Circuit-Tracer命令详解：从CLI到Python API的完整使用手册

【免费下载链接】circuit-tracer 项目地址: https://gitcode.com/gh_mirrors/ci/circuit-tracer

Circuit-Tracer是一款强大的神经网络电路分析工具，它能够帮助开发者深入理解大型语言模型内部的工作机制。通过直观的图形化界面和灵活的命令行接口，你可以轻松生成、分析和可视化模型的注意力模式与神经元激活路径。无论你是AI研究人员还是机器学习爱好者，掌握Circuit-Tracer的使用方法都将为你的模型调试与优化工作带来巨大帮助。

快速开始：安装与基础配置

要开始使用Circuit-Tracer，首先需要克隆项目仓库并安装依赖：

git clone https://gitcode.com/gh_mirrors/ci/circuit-tracer
cd circuit-tracer
pip install -r requirements.txt

Circuit-Tracer支持两种主流后端：transformerlens和nnsight，默认使用transformerlens。你可以根据需求在命令行或API调用中指定后端类型。

CLI命令全解析：从基础到高级

Circuit-Tracer提供了直观的命令行接口，让你无需编写代码即可执行复杂的电路分析任务。主要命令包括attribute（执行归因分析）和start-server（启动可视化服务器）。

基础归因分析命令

最常用的命令是执行归因分析并生成可视化结果：

python -m circuit_tracer attribute \
  --model meta-llama/Llama-2-7b-hf \
  --transcoder_set your-username/transcoder-set \
  --prompt "The opposite of 'small' is '" \
  --slug llama-small-opposite \
  --graph_file_dir ./graphs \
  --server

这个命令将：

• 使用Llama-2-7b模型分析给定提示
• 从HuggingFace Hub加载指定的transcoder集
• 生成电路分析结果并保存到./graphs目录
• 自动启动本地服务器以可视化结果

关键参数详解

参数	作用	示例
--model	指定要分析的模型名称	meta-llama/Llama-2-7b-hf
--transcoder_set	指定transcoder集的HuggingFace仓库ID	username/transcoder-repo
--prompt	输入要分析的文本提示	"The capital of France is "
--dtype	指定模型数据类型	float16（节省显存）
--backend	选择后端框架	nnsight或transformerlens
--offload	启用模型参数卸载	cpu或disk（内存不足时使用）
--server	分析后启动可视化服务器	无需值， presence即启用

服务器启动命令

如果已经生成了分析结果，可直接启动服务器查看：

python -m circuit_tracer start-server \
  --graph_file_dir ./graphs \
  --port 8041

启动后访问http://localhost:8041即可看到交互式可视化界面。

Python API使用指南

对于需要更高级定制的场景，Circuit-Tracer提供了灵活的Python API，让你可以将电路分析功能集成到自己的工作流中。

基础API示例

以下是使用Python API执行归因分析的基本示例：

from circuit_tracer import ReplacementModel, attribute
from circuit_tracer.utils.hf_utils import load_transcoder_from_hub

# 加载transcoder集
transcoder, config = load_transcoder_from_hub(
    "username/transcoder-set",
    dtype="float16",
    lazy_decoder=True
)

# 创建模型实例
model = ReplacementModel.from_pretrained_and_transcoders(
    "meta-llama/Llama-2-7b-hf",
    transcoder,
    backend="transformerlens",
    dtype="float16"
)

# 执行归因分析
graph = attribute(
    prompt="The opposite of 'small' is '",
    model=model,
    max_n_logits=10,
    desired_logit_prob=0.95,
    batch_size=256
)

# 保存结果
graph.to_pt("attribution_result.pt")

核心API组件

Circuit-Tracer的核心API组件位于circuit_tracer/replacement_model/replacement_model.py，主要包括：

1. ReplacementModel类：统一的模型接口，支持不同后端

   • from_pretrained(): 从预训练模型创建实例
   • from_pretrained_and_transcoders(): 结合transcoder创建实例

2. attribute函数：执行归因分析的核心函数

   • 支持自定义批处理大小、logit阈值等参数
   • 返回可序列化的图对象，便于后续分析和可视化

3. 可视化工具：通过circuit_tracer/frontend/local_server.py提供的serve()函数启动可视化服务器

可视化分析：解读电路追踪结果

Circuit-Tracer提供了强大的可视化功能，帮助你直观理解模型内部的工作机制。分析结果以交互式图形展示，你可以探索神经元之间的连接强度、关键特征的传播路径等。

Circuit-Tracer多语言电路分析示例：展示了模型在处理不同语言反义词任务时的内部电路激活模式

可视化界面主要包含：

• 节点：代表神经元或特征
• 边：表示节点间的连接强度
• 交互式控制：缩放、平移、筛选节点
• 详细信息面板：显示选中节点的详细激活数据

电路节点连接图示例：展示了模型处理"Zagreb is the capital of Croatia; Copenhagen is the capital of"提示时的特征激活路径

高级技巧与最佳实践

内存优化策略

处理大型模型时，内存可能成为瓶颈。以下是一些优化建议：

1. 使用低精度数据类型：--dtype float16或bfloat16
2. 启用参数卸载：--offload cpu或--offload disk
3. 启用延迟加载：--lazy-encoder和--lazy-decoder标志
4. 减小批处理大小：--batch_size 128（默认256）

自定义分析工作流

对于高级用户，可以通过组合以下模块创建自定义分析工作流：

• circuit_tracer/attribution/: 归因分析核心算法
• circuit_tracer/transcoder/: 特征转换与编码
• circuit_tracer/utils/: 辅助工具函数，包括缓存、磁盘卸载等

常见问题与故障排除

Q: 模型加载时出现内存不足错误怎么办？

A: 尝试使用低精度数据类型（--dtype float16）、启用参数卸载（--offload cpu）或减小批处理大小。

Q: 如何选择合适的transcoder集？

A: 不同模型架构需要对应的transcoder集。你可以在HuggingFace Hub搜索与模型匹配的transcoder，或使用circuit_tracer/utils/create_graph_files.py工具生成自定义transcoder。

Q: 可视化服务器无法启动怎么办？

A: 检查端口是否被占用（默认8041），可使用--port参数指定其他端口。同时确保--graph_file_dir包含有效的JSON图文件。

总结

Circuit-Tracer提供了从命令行到Python API的完整解决方案，帮助你深入理解和分析大型语言模型的内部工作机制。通过本文介绍的CLI命令和API使用方法，你可以快速上手并将电路分析集成到你的AI开发工作流中。无论是模型调试、神经元研究还是特征分析，Circuit-Tracer都能为你提供强大的支持。

开始探索你的模型电路，发现AI黑箱内部的奥秘吧！ 🚀

【免费下载链接】circuit-tracer 项目地址: https://gitcode.com/gh_mirrors/ci/circuit-tracer