neuronpedia.org 🧠🔍

开源可解释性平台
_{API · 引导 · 激活值 · 电路/图谱 · 自动解释 · 评分 · 推理 · 搜索 · 过滤 · 仪表盘 · 基准测试 · 余弦相似度 · UMAP · 嵌入 · 探针 · SAE · 列表 · 导出 · 上传}

• 关于 Neuronpedia
• 设置本地环境
  • "我想使用本地数据库 / 导入更多 Neuronpedia 数据"
  • "我想进行 Web 应用开发（前端 + API）"
  • "我想在本地运行/开发推理功能"
  • '我想在本地运行/开发图谱服务器'
  • '我想在本地运行/开发自动解释功能'
  • '我想进行高吞吐量的自动解释'
  • '我想生成自己的仪表盘/数据并添加到 Neuronpedia 中'
• 架构
  • 要求
  • 服务
    • [服务是独立的应用程序] (#services-are-standalone-apps)
    • [服务特定文档] (#service-specific-documentation)
  • [OpenAPI 模式] (#openapi-schema)
  • [Monorepo 目录结构] (#monorepo-directory-structure)
• 安全
• [联系 / 支持] (#contact--support)
• 贡献
• [附录] (#appendix)
  • ['Make' 命令参考] (#make-commands-reference)
  • [将数据导入本地数据库] (#import-data-into-your-local-database)
  • [为什么搜索解释需要 OpenAI API 密钥] (#why-an-openai-api-key-is-needed-for-search-explanations)

关于 Neuronpedia

请查看我们的博客文章，了解有关 Neuronpedia 的信息、我们开源它的原因以及其他细节。此外，还有一个包含快速演示的Twitter 线程。

功能概览

一张展示截至 2025 年 3 月 Neuronpedia 主要功能的示意图。

设置本地环境

首先设置你的本地数据库。

🔥 小贴士： Neuronpedia 针对 AI 代理开发进行了配置。以下是一个使用单个提示构建自定义应用（Steerify）的例子，该应用以 Neuronpedia 的推理服务器作为后端：

https://github.com/user-attachments/assets/bc82f88b-8155-4c1d-948a-ea5d987ae0f8

“我想使用本地数据库 / 导入更多 Neuronpedia 数据”

这些步骤的作用及你将获得的内容

这些步骤将指导你如何配置并连接到自己的本地数据库。随后，你可以下载自己选择的数据源/SAE：

https://github.com/user-attachments/assets/d7fbb46e-8522-4f98-aa08-21c6529424af

⚠️ 警告： 你的数据库初始为空。你需要使用管理面板来导入数据（激活值、解释等）。

⚠️ 警告： 本地数据库环境中没有连接任何推理服务器，因此你最初无法进行激活测试、引导等操作。你需要配置一个本地推理实例。

步骤

1. 构建 Web 应用

   make webapp-localhost-build
   

2. 启动 Web 应用

   make webapp-localhost-run
   

3. 访问 localhost:3000 查看你的本地 Web 应用实例，它现已连接到你的本地数据库
4. 参阅上述“警告”部分以及“后续步骤”，完成设置

后续步骤

1. 点击此处了解如何将数据导入本地数据库（激活值、解释等），因为你的本地数据库初始为空
2. 点击此处了解如何为你正在使用的模型/数据源/SAE 启动一个本地“推理”服务

“我想进行 Web 应用（前端 + API）开发”

这部分的作用

到目前为止，你一直在构建的 Web 应用都是 生产构建，这种构建方式虽然运行速度快，但构建过程较慢。由于生产构建速度慢且不包含调试信息，因此并不适合开发使用。

本小节会在你的本地机器上安装开发构建版本（不使用 Docker），然后将该构建挂载到你的 Docker 容器中。

你将获得什么

完成本小节后，你就可以在本地进行开发，并能快速看到代码更改的效果，同时还能看到更详细的调试信息和错误提示。如果你只是想专注于 Neuronpedia 的前端或 API 开发，那么无需再进行其他设置！

操作步骤

1. 通过 Node 版本管理工具 安装 Node.js：

   make install-nodejs
   

2. 安装 Web 应用的依赖项：

   make webapp-localhost-install
   

3. 启动开发实例：

   make webapp-localhost-dev
   

4. 打开 localhost:3000，即可查看你的本地 Web 应用实例。

在本地进行 Web 应用开发

• 自动刷新：当你修改 apps/webapp 子目录中的任何文件时，localhost:3000 会自动重新加载。
• 安装命令：你无需再次运行 make install-nodejs，并且只有在依赖项发生变化时才需要运行 make webapp-localhost-install。

“我想在本地运行/开发推理”

这部分的作用及你将获得的内容

本小节将向你展示如何在本地运行一个推理实例，以便你可以对你下载的源数据或 SAE 集合进行引导、激活测试等操作。

⚠️ 警告： 在本地环境中，我们仅支持同时运行一个推理服务器。这是因为你在同一台机器上不太可能同时运行多个模型，因为这些模型对内存和计算资源的需求都非常高。

操作步骤

1. 确保你已安装 Poetry。

2. 安装推理服务器的依赖项：

   make inference-localhost-install
   

3. 根据你的机器是否配备 CUDA 来构建镜像：

   # CUDA
   make inference-localhost-build-gpu USE_LOCAL_HF_CACHE=1
   

   # 无 CUDA
   make inference-localhost-build USE_LOCAL_HF_CACHE=1
   

   ➡️ USE_LOCAL_HF_CACHE=1 标志会将你本地的 HuggingFace 缓存挂载到 ${HOME}/.cache/huggingface/hub:/root/.cache/huggingface/hub。如果你希望在容器中创建一个新的缓存，可以在此处以及下一步中省略该标志。

4. 运行推理服务器，使用 MODEL_SOURCESET 参数指定你要加载的 .env.inference.[model_sourceset] 文件。以本示例为例，我们将运行 gpt2-small，并加载配置在 .env.inference.gpt2-small.res-jb 文件中的 res-jb 源数据集/SAE 集合。你也可以查看其他预加载的推理配置，或者创建自己的配置。

   # CUDA
   make inference-localhost-dev-gpu \
        MODEL_SOURCESET=gpt2-small.res-jb \
        USE_LOCAL_HF_CACHE=1
   
   # 无 CUDA
   make inference-localhost-dev \
        MODEL_SOURCESET=gpt2-small.res-jb \
        USE_LOCAL_HF_CACHE=1
   

5. 等待加载完成（首次启动会较慢）。当看到 Initialized: True 时，本地推理服务器已在 localhost:5002 上准备就绪。

使用推理服务器

要与推理服务器交互，你有几种选择——请注意，这仅适用于你已加载的模型和选定的源数据：

1. 加载带有本地数据库设置的 Web 应用程序，然后像在 Neuronpedia 上一样正常使用模型和选定的源数据。
2. 使用位于 packages/python/neuronpedia-inference-client 的预生成推理 Python 客户端（将环境变量 INFERENCE_SERVER_SECRET 设置为 public，或者根据你在 .env.localhost 中的设置进行调整）。
3. 使用位于 schemas/openapi/inference-server.yaml 的 OpenAPI 规范，通过任何你喜欢的客户端发起调用。服务器启动后，你可以在 /docs 获得交互式的 Swagger 文档。详细信息请参阅 apps/inference/README.md。

预加载的推理服务器配置

我们提供了一些预加载的推理配置，作为如何加载特定模型和源数据集进行推理的示例。可通过运行 make inference-list-configs 查看：

$ make inference-list-configs

可用的推理配置 (.env.inference.*)
================================================

deepseek-r1-distill-llama-8b.llamascope-slimpj-res-32k
    模型：meta-llama/Llama-3.1-8B
    源/SAE 集合：'["llamascope-slimpj-res-32k"]'
    make inference-localhost-dev MODEL_SOURCESET=deepseek-r1-distill-llama-8b.llamascope-slimpj-res-32k

gemma-2-2b-it.gemmascope-res-16k
    模型：gemma-2-2b-it
    源/SAE 集合：'["gemmascope-res-16k"]'
    make inference-localhost-dev MODEL_SOURCESET=gemma-2-2b-it.gemmascope-res-16k

gpt2-small.res-jb
    模型：gpt2-small
    源/SAE 集合：'["res-jb"]'
    make inference-localhost-dev MODEL_SOURCESET=gpt2-small.res-jb

创建你自己的推理服务器配置

可参考 .env.inference.* 文件，了解如何制作这些推理服务器配置。

MODEL_ID 是来自 transformerlens 模型表的模型 ID，而每个 SAE_SETS 则是 Neuronpedia 源 ID 中层号和连字符之后的部分——例如，如果你有一个 Neuronpedia 特征的 URL 是 http://neuronpedia.org/gpt2-small/0-res-jb/123，那么 0-res-jb 就是源 ID，而 SAE_SETS 中的条目就是 res-jb。此示例与 .env.inference.gpt2-small.res-jb 文件完全一致。

你可以在 saelens 的预训练 SAE YAML 文件中找到 Neuronpedia 源 ID，或者通过点击进入 Neuronpedia 数据集导出目录来查找。

使用 TransformerLens 官方不支持的模型

可参考 .env.inference.deepseek-r1-distill-llama-8b.llamascope-slimpj-res-32k 文件，了解如何加载 TransformerLens 官方不支持的模型。这主要用于替换蒸馏或微调后的权重。

加载非 Saelens 的源数据/SAE

• 待办事项 #2 记录了如何加载不在 saelens 预训练 YAML 文件中的 SAE 或源数据。

进行本地推理开发

• 基于 schema 的开发：若要添加新端点或更改现有端点，你需要先更新 OpenAPI schema，然后从中生成客户端，最后再更新实际的推理和 Web 应用程序代码。有关具体操作方法，请参阅 OpenAPI 说明文档：修改推理服务器。
• 无自动重载：当你更改 apps/inference 子目录中的任何文件时，推理服务器不会自动重新加载，因为服务器重启非常耗时——它会重新加载模型以及所有源数据和 SAE。如果你想启用自动重载，可以在 make inference-localhost-dev 命令中添加 AUTORELOAD=1，如下所示：

  make inference-localhost-dev \
       MODEL_SOURCESET=gpt2-small.res-jb \
       AUTORELOAD=1
  

‘我想在本地运行/开发图服务器’

这能做什么 + 你会得到什么

图服务器为归因图生成功能提供支持，该功能基于 Piotrowski 和 Hanna 开发的 circuit-tracer 构建。当您通过 Neuronpedia Circuit Tracer 界面创建新图时，此服务会处理后端流程。

步骤

1. 确保已安装 Poetry
2. 安装图服务器的依赖项：

   make graph-localhost-install
   

3. 在 apps/graph 目录下，创建一个包含 SECRET 和 HF_TOKEN 的 .env 文件（参见 apps/graph/.env.example）：
   • SECRET 是服务器密钥，需在 x-secret-key 请求头中传递。
   • 确保您的 HF_TOKEN 具有访问 Hugging Face 上 Gemma-2-2B 模型的权限。
4. 根据机器是否配备 CUDA，选择正确的命令来构建镜像：

   # CUDA
   make graph-localhost-build-gpu USE_LOCAL_HF_CACHE=1
   

   # 无 CUDA
   make graph-localhost-build USE_LOCAL_HF_CACHE=1
   

   ➡️ USE_LOCAL_HF_CACHE=1 标志会将您本地的 Hugging Face 缓存挂载到 ${HOME}/.cache/huggingface/hub:/root/.cache/huggingface/hub。如果您希望在容器内创建新的缓存，则可以在此处及下一步省略此标志。

5. 运行图服务器：

   # CUDA
   make graph-localhost-dev-gpu \
        USE_LOCAL_HF_CACHE=1
   
   # 无 CUDA
   make graph-localhost-dev \
        USE_LOCAL_HF_CACHE=1
   

6. 等待容器启动。

有关示例请求，请参阅 图服务器 README。

‘我想在本地运行/开发自动解释器’

这能做什么 + 你会得到什么

自动解释器服务器提供对神经网络特征的自动解释和评分功能。它使用 eleutherAI 的 delphi 来生成解释并进行评分。

⚠️ 警告： eleuther 嵌入评分器使用的嵌入模型仅支持 CUDA（无法在 Mac MPS 或 CPU 上运行）。

步骤

1. 确保已安装 Poetry
2. 安装自动解释器服务器的依赖项：

   make autointerp-localhost-install
   

3. 根据机器是否配备 CUDA，选择正确的命令来构建镜像：

   # CUDA
   make autointerp-localhost-build-gpu USE_LOCAL_HF_CACHE=1
   

   # 无 CUDA
   make autointerp-localhost-build USE_LOCAL_HF_CACHE=1
   

   ➡️ USE_LOCAL_HF_CACHE=1 标志会将您本地的 Hugging Face 缓存挂载到 ${HOME}/.cache/huggingface/hub:/root/.cache/huggingface/hub。如果您希望在容器内创建新的缓存，则可以在此处及下一步省略此标志。

4. 运行自动解释器服务器：

   # CUDA
   make autointerp-localhost-dev-gpu \
        USE_LOCAL_HF_CACHE=1
   
   # 无 CUDA
   make autointerp-localhost-dev \
        USE_LOCAL_HF_CACHE=1
   

5. 等待加载完成。

使用自动解释器服务器

要与自动解释器服务器交互，您可以选择以下几种方式：

1. 使用预生成的自动解释器 Python 客户端，位于 packages/python/neuronpedia-autointerp-client（将环境变量 AUTOINTERP_SERVER_SECRET 设置为 public，或根据您在 .env.localhost 中的设置进行更改）。
2. 使用 OpenAPI 规范文件，位于 schemas/openapi/autointerp-server.yaml，以便使用您选择的任何客户端发起调用。服务器启动后，您可以在 /docs 获取 Swagger 交互式规范。详细信息请参阅 apps/inference/README.md。

进行本地自动解释器开发

• 基于 schema 的开发：要添加新端点或更改现有端点，您需要先更新 OpenAPI schema，然后从中生成客户端，最后再更新实际的自动解释器和 Web 应用程序代码。有关具体操作方法，请参阅 OpenAPI README：修改自动解释器服务器。
• 无自动重载：当您更改 apps/autointerp 子目录中的任何文件时，默认情况下自动解释器服务器不会自动重新加载。如果您希望启用自动重载，可在 make autointerp-localhost-dev 命令中附加 AUTORELOAD=1，如下所示：

  make autointerp-localhost-dev \
       AUTORELOAD=1
  

‘我想进行高容量的自动解释说明’

本节正在建设中。

• 使用 EleutherAI 的 Delphi 库。
• 对于 OpenAI 的自动解释，可使用 utils/neuronpedia_utils/batch-autointerp.py。

‘我想生成自己的仪表板/数据，并将其添加到 Neuronpedia’

本节正在建设中。

待办事项：简化数据生成及上传至 Neuronpedia 的流程

待办事项：neuronpedia-utils 应使用 Poetry

在本示例中，我们将为一个与 SAELens 兼容的 SAE 生成仪表板/数据，并将其上传到我们自己的 Neuronpedia 实例。

1. 确保已安装 Poetry。

2. 将您与 SAELens 兼容的源代码/SAE 上传 至 HuggingFace。

   示例 ➡️ https://huggingface.co/chanind/gemma-2-2b-batch-topk-matryoshka-saes-w-32k-l0-40

3. 在本地克隆 SAELens。

   git clone https://github.com/jbloomAus/SAELens.git
   

4. 打开您克隆的 SAELens，并编辑文件 sae_lens/pretrained_saes.yaml。根据下方模板，在文件末尾添加一条新条目（请参阅注释以了解如何填写）：

   示例 ➡️ https://github.com/jbloomAus/SAELens/pull/455/files

   gemma-2-2b-res-matryoshka-dc:                 # 您 SAE 集合的唯一标识符
     conversion_func: null                       # 如果您的 SAE 配置已与 SAELens 兼容，则设为 null
     links:                                      # 可选链接
       model: https://huggingface.co/google/gemma-2-2b
     model: gemma-2-2b                           # TransformerLens 模型 ID - https://transformerlensorg.github.io/TransformerLens/generated/model_properties_table.html
     repo_id: chanind/gemma-2-2b-batch-topk-matryoshka-saes-w-32k-l0-40  # HuggingFace 仓库路径
     saes:
     - id: blocks.0.hook_resid_post                 # 此 SAE 的标识符
       path: standard/blocks.0.hook_resid_post      # 仓库路径中指向该 SAE 的位置
       l0: 40.0
       neuronpedia: gemma-2-2b/0-matryoshka-res-dc  # 您期望的 Neuronpedia URI - neuronpedia.org/[此_slug]。应为 [模型ID]/[层]-[与此 SAE 集相同的 slug]
     - id: blocks.1.hook_resid_post                 # 此 SAE 集中的更多 SAE
       path: standard/blocks.1.hook_resid_post
       l0: 40.0
       neuronpedia: gemma-2-2b/1-matryoshka-res-dc  # 注意，此处与上方条目相同，只是层号从 0 改为 1
     - [...]
   

5. 在本地克隆 SAEDashboard。

   git clone https://github.com/jbloomAus/SAEDashboard.git
   

6. 配置您克隆的 SAEDashboard 以使用您修改后的本地 SAELens，而非生产环境中的版本。

   cd SAEDashboard                    # 进入目录
   poetry lock && poetry install      # 安装依赖
   poetry remove sae-lens             # 移除生产依赖
   poetry add PATH/TO/CLONED/SAELENS  # 设置本地依赖
   

7. 为 SAE 生成仪表板。这将耗时 30 分钟至数小时不等，具体取决于您的硬件和模型规模。

   cd SAEDashboard                    # 进入目录
   rm -rf cached_activations          # 清除旧的缓存数据
   
   # 开始生成。各参数说明如下（详细信息：https://github.com/jbloomAus/SAEDashboard/blob/main/sae_dashboard/neuronpedia/neuronpedia_runner_config.py）
   #     - sae-set = 应与 pretrained_saes.yaml 中该集合的唯一标识符匹配
   #     - sae-path = 应与 pretrained_saes.yaml 中该 SAE 的标识符匹配
   #     - np-set-name = 应与 pretrained_saes.yaml 中该 SAE 的 neuronpedia 字段所指定的 [与此 SAE 集相同的 slug] 匹配
   #     - dataset-path = 用于生成激活值的 HuggingFace 数据集。通常建议使用模型训练时所用的数据集。
   #     - output-dir = 仪表板数据的输出目录
   #     - n-prompts = 从数据集中测试的激活文本数量
   #     - n-tokens-in-prompt、n-features-per-batch、n-prompts-in-forward-pass = 保持为 128
   poetry run neuronpedia-runner \
        --sae-set="gemma-2-2b-res-matryoshka-dc" \
        --sae-path="blocks.12.hook_resid_post" \
        --np-set-name="matryoshka-res-dc" \
        --dataset-path="monology/pile-uncopyrighted" \
        --output-dir="neuronpedia_outputs/" \
        --sae_dtype="float32" \
        --model_dtype="bfloat16" \
        --sparsity-threshold=1 \
        --n-prompts=24576 \
        --n-tokens-in-prompt=128 \
        --n-features-per-batch=128 \
        --n-prompts-in-forward-pass=128
   

8. 将这些仪表板转换为可导入 Neuronpedia 的格式。

   cd neuronpedia/utils/neuronpedia-utils          # 进入当前仓库的工具目录
   python convert-saedashboard-to-neuronpedia.py   # 启动引导式转换脚本，按照步骤操作。
   

9. 一旦为 Neuronpedia 生成了仪表板文件，便将其上传至全球 Neuronpedia S3 存储桶——目前您需要通过 联系我们 来完成此操作。

10. 在本地实例上，导入您的数据。

架构

以下是 Neuronpedia 中各服务/脚本之间的连接方式。阅读此图时，建议从笔记本电脑图像（“用户”）开始。

要求

您可以在任何云平台和现代操作系统上运行 Neuronpedia。Neuronpedia 的设计旨在避免供应商锁定。本指南是在 macOS 15（Sequoia）上编写并测试的，因此您可能需要针对 Windows、Ubuntu 等系统调整命令。建议至少配备 16GB 内存。

服务

名称	描述	技术栈
webapp	提供 neuronpedia.org 前端及 API	next.js / react
database	存储特征、激活值、解释、用户、列表等信息	postgres
inference	[支持服务器] 方向控制、激活测试、通过推理进行搜索、topk 等功能。每运行一个模型的推理，都需要单独的实例。	python / torch
autointerp	[支持服务器] 使用 eleutherAI 的 delphi（原 sae-auto-interp）自动生成解释和评分。	python

服务是独立的应用程序

根据设计，每个服务都可以作为独立的应用程序单独运行。这样做的目的是为了提高可扩展性和可分叉性。

例如，如果你喜欢 Neuronpedia 的 Web 应用前端，但想使用不同的 API 进行推理，你完全可以做到！只需确保你的替代推理服务器支持 schema/openapi/inference-server.yaml 规范，或者修改 apps/webapp/lib/utils 中调用推理的部分即可。

服务特定文档

目前在 apps/[service] 目录下有针对每个应用/服务的草稿 README，但这些文档仍在 heavily WIP 阶段。你也可以查看同一目录下的 Dockerfile 来构建自己的镜像。

OpenAPI 模式

为了让各个服务之间能够以类型安全且一致的方式进行通信，我们使用 OpenAPI 模式。当然也有一些例外情况——比如流式传输并不被 OpenAPI 规范正式支持。不过即便如此，我们仍然会尽力定义并使用相应的模式。

尤其对于推理和自动解释服务器的开发来说，理解并遵循 OpenAPI README 中的说明至关重要。

OpenAPI 模式的文件位于 /schemas 目录下。我们使用 OpenAPI 生成工具来分别生成 TypeScript 和 Python 客户端。

单仓库目录结构

apps - Neuronpedia 的三个服务：webapp、inference 和 autointerp。大部分代码都放在这里。 schemas - OpenAPI 模式。如果要修改推理和自动解释的接口，首先需要修改它们的模式——详情请参阅 OpenAPI README。 packages - 由 schemas 使用生成工具生成的客户端。通常情况下，你不需要手动修改这些文件。 utils - 各种实用工具，用于执行离线处理任务，比如大批量的自动解释、生成仪表盘或导出数据等。

安全

请将漏洞报告发送至 johnny@neuronpedia.org。

我们目前还没有正式的漏洞赏金计划，但我们会根据漏洞的严重程度尽力给予补偿——尽管对于低危漏洞，我们可能无法提供奖励。

联系方式 / 支持

• Slack: 加入 #neuronpedia
• 邮箱: johnny@neuronpedia.org
• 问题: GitHub issues

贡献

请参阅 CONTRIBUTING.md。

附录

make 命令参考

你可以通过运行 make help 查看所有可用的 make 命令及其简要说明。

将数据导入本地数据库

如果你设置了属于自己的数据库，它一开始将是空的——没有特征、解释、激活值等。要加载这些数据，可以使用内置的“管理面板”，从中下载你选择的 SAE（或“源”）的数据。

⚠️ 警告: 管理面板比较挑剔，目前不支持断点续传。如果导入过程中断，你必须手动点击“重新同步”。管理面板目前不会检查下载是否完整或是否有缺失部分——你需要自己确认数据是否完整，如果不完整则需点击“重新同步”以重新下载整个数据集。

ℹ️ 建议: 导入数据时，建议先从一个源开始（比如 gpt2-small@10-res-jb），而不是一次性下载所有数据。这样更容易验证数据是否正确导入，并能更快地开始使用 Neuronpedia。

以下步骤演示如何下载 gpt2-small@10-res-jb 的 SAE 数据。

1. 打开 localhost:3000/admin。
2. 向下滚动到 gpt2-small，然后展开 res-jb。
3. 点击 10-res-jb 旁边的“下载”按钮。
4. 请耐心等待——这可能会涉及大量数据，具体时间取决于你的网络连接和 CPU 速度，可能需要 30 分钟甚至一个小时。
5. 下载完成后，点击“浏览”或使用导航栏尝试使用：跳转、搜索、方向控制。
6. 对其他你想下载的 SAE/源数据重复上述步骤。

为什么搜索解释功能需要 OpenAI API 密钥

在 Web 应用中，“搜索解释”功能要求你设置一个 OPENAI_API_KEY。否则你将无法获得任何搜索结果。

这是因为“搜索解释”功能是通过语义相似度来查找特征的。例如，如果你搜索“猫”，它也会返回“猫科动物”、“虎斑猫”、“动物”等。要做到这一点，系统需要计算你输入“猫”的嵌入向量。我们使用 OpenAI 的嵌入 API（具体为 text-embedding-3-large，维度为 256）来计算这些嵌入向量。

Neuronpedia 快速上手指南

Neuronpedia 是一个开源的模型可解释性平台，支持神经元激活分析、电路可视化、自动解释（Autointerp）、 Steering（干预）等功能。本指南帮助中国开发者快速在本地搭建基础环境并运行核心服务。

环境准备

系统要求

• 操作系统: Linux (推荐 Ubuntu 20.04+) 或 macOS
• GPU (可选但推荐): 如需运行本地推理（Inference）或处理大模型，需配备 NVIDIA GPU 及 CUDA 环境。无 GPU 亦可运行 Web 端和数据库，但无法进行实时激活测试。
• 内存: 建议 16GB+（运行大模型推理需更多）

前置依赖

请确保已安装以下工具：

• Docker & Docker Compose: 用于编排数据库和服务容器。
• Make: 用于执行项目定义的自动化命令。
• Node.js & NVM: 用于前端开发（可选，仅当需要修改前端代码时）。
• Poetry: Python 包管理工具，用于推理服务依赖管理。
• Git: 克隆代码仓库。

国内加速建议：

• 拉取 Docker 镜像时，建议配置国内镜像加速器（如阿里云、腾讯云等）。
• 安装 Python/Node 依赖时，可临时指定国内源（如 pip install -i https://pypi.tuna.tsinghua.edu.cn/simple），但在执行本项目 make 命令时，请优先遵循项目默认配置以确保兼容性。

安装步骤

1. 克隆项目

git clone https://github.com/hijohnnylin/neuronpedia.git
cd neuronpedia

2. 启动本地数据库与 Web 应用

这是最基础的运行方式，用于浏览数据和导入自定义数据源。

# 构建 Web 应用
make webapp-localhost-build

# 启动 Web 应用（连接本地空数据库）
make webapp-localhost-run

启动完成后，访问 http://localhost:3000 即可看到本地实例。

注意：初次启动数据库为空，需通过后台管理面板导入数据（见“基本使用”部分）。

3. (可选) 配置本地推理服务

若需进行激活测试、Steering 或自动解释，需启动推理服务器。

安装依赖：

# 确保已安装 Poetry
make inference-localhost-install

构建并运行（根据是否有 GPU 选择命令）：

• 有 CUDA 环境：

  make inference-localhost-dev-gpu \
       MODEL_SOURCESET=gpt2-small.res-jb \
       USE_LOCAL_HF_CACHE=1
  

• 无 CUDA 环境（CPU 模式，速度较慢）：

  make inference-localhost-dev \
       MODEL_SOURCESET=gpt2-small.res-jb \
       USE_LOCAL_HF_CACHE=1
  

参数说明：

• MODEL_SOURCESET: 指定要加载的模型和数据集组合（例如 gpt2-small.res-jb）。可通过 make inference-list-configs 查看支持的配置。
• USE_LOCAL_HF_CACHE=1: 挂载本地 HuggingFace 缓存，避免重复下载模型权重。

等待终端输出 Initialized: True 后，推理服务将在 localhost:5002 就绪。

基本使用

1. 导入数据到本地数据库

由于本地数据库初始为空，您需要导入神经元激活数据、解释数据等。

1. 访问 http://localhost:3000 登录管理面板（首次使用可能需要注册管理员账号，具体参考界面提示）。
2. 在 Admin Panel 中找到 Import Sources/Data 选项。
3. 上传或指定您想要分析的 SAE (Sparse Autoencoder) 源文件和激活数据。
   • 您可以从 Neuronpedia 官方导出数据包，或使用自己生成的数据。

2. 探索神经元与可视化

数据导入成功后：

1. 在 Web 界面搜索特定的神经元（Neuron）或特征（Feature）。
2. 查看该神经元的激活分布、Top 激活样本以及自动生成的自然语言解释。
3. 如果已启动本地推理服务，您可以：
   • 进行 Activation Testing：输入文本查看特定神经元的响应。
   • 进行 Steering：手动干预神经元激活值，观察模型输出的变化。

3. 开发者模式（前端修改）

如果您需要修改前端代码或 API 逻辑，请使用开发模式构建，以支持热重载：

# 安装 Node 环境
make install-nodejs

# 安装前端依赖
make webapp-localhost-install

# 启动开发服务器
make webapp-localhost-dev

此后，修改 apps/webapp 目录下的文件，浏览器将自动刷新。

---

注：更多高级功能（如大规模自动解释、自定义 Dashboard 生成）请参考项目根目录下的详细文档。