🔍 LLM 调试（Debugging）

开发过程中的可观测性工具，帮助你看到每一步 Prompt、每次 Tool Call、每个 Token 消耗。

为什么需要专门的调试工具？

LLM 应用的调试与传统代码调试有本质区别：

  • ❌ 输出非确定性：同样的 prompt，LLM 每次可能输出不同结果
  • ❌ 内部状态不透明：你看不到模型"思考"了什么、选了哪个工具
  • ❌ Agent 链路复杂：多步循环、工具调用、上下文膨胀，很难定位问题
  • ✅ 调试工具的核心目标：把黑盒调用变成白盒分析
核心工具

1. LLM Space — Agent 的 IDE

🔬
LLM Space
v4.1.1 · 字节跳动开源

桌面级 Agent 开发调试工作台（可理解为 Agent 的 IDE），自带 harness 运行时，核心差异化在于把 harness 的每一次执行都「可观测、可回放、可评估」。

五大核心模块

🔨
Build 构建
编写并版本化管理提示词、系统消息、工具定义和模型设置
🔍
Trace 追踪
实时查看 Agent 循环内的每次模型调用、工具执行、token 消耗
🐛
Debug 调试
从历史记录重放任意运行，支持单步执行（Step-through）
📊
Evaluate 评估
跨多次运行衡量表现，支持自定义评估指标和批量对比
📁
Manage 管理
以文件形式在本地组织会话（threads），支持搜索、标签、归档

安装方式

# macOS / Windows 直接下载安装包
# https://github.com/deer-flow/llm-space/releases

# 安装后首次启动需配置模型 Provider
# 支持：OpenAI / Anthropic / Google / 本地 Ollama 等

Debug 核心技巧

1
制造多次 Run

修改 system prompt 或换模型后多次 Run，所有运行历史都会保留在 Run History 中

2
启动 Replay 模式

点开某次历史运行 → 进入 Debug/Replay，LLM Space 将完整状态冻结

3
单步执行

逐步执行 User Message → Model Call → Tool Selection → Tool Execution → Final Response

4
修改并重试

在 Replay 中修改 Prompt/工具参数/Mock 返回值，从该点往后重跑

💡
Thread 是什么？

Thread = 一次实验的完整载体，落地为单个 .json 文件（~/.llm-space/workspace/*.json）。包含 system prompt / variables / tools / model / messages（含 tool calls 历史）/ runHistory / evaluationRubrics / evaluations。

• • •

2. Langfuse — 开源 LLM 工程平台

📊
Langfuse
开源 / 商业版 · 支持 Python + TypeScript

开源 LLM 工程平台，提供追踪（Tracing）、成本分析、提示词管理和评估功能。支持 OpenTelemetry 标准，可自托管。

核心能力

  • 全链路追踪：每一步 LLM 调用、Tool 调用的完整记录
  • 成本与延迟分析：token 使用统计、费用预估、延迟分布
  • Prompt 版本管理：支持 A/B 测试和版本对比
  • 评估（Evaluation）：LLM-as-Judge 自动打分
  • 数据集管理：测试用例集批量跑评测

Python SDK 使用示例

# 安装
pip install langfuse

# 初始化
from langfuse import Langfuse
langfuse = Langfuse(
  public_key="pk-lf-xxx",
  secret_key="sk-lf-xxx"
)

# 追踪一次 LLM 调用
trace = langfuse.trace(name="agent-session")
span = trace.span(name="llm-call")

# ... 你的 LLM 调用 ...
span.end(output=llm_response)
trace.update(output=final_response)

部署方式

Cloud 版（SaaS）

  • 零部署，注册即用
  • 免费额度充足
  • 数据存于 Langfuse 云端
  • 适合原型和中小团队

自托管（Self-hosted）

  • Docker Compose 一键部署
  • 数据完全自主可控
  • PostgreSQL + ClickHouse
  • 适合企业和合规场景
官网 Cloud 控制台 GitHub 文档
• • •

3. Claude Tap — 浏览器扩展调试

🎛️
Claude Tap
Chrome 扩展 · 开源

Chrome 浏览器扩展，为 Claude.ai 增加网络请求面板，可捕获每一次 API 调用的 prompt、response、token 消耗。

核心功能

  • 捕获 Claude.ai 的网络请求细节（API 调用 body）
  • 查看完整 system prompt 和消息历史（含中间步骤）
  • 展示 token 使用量和预估成本
  • 导出对话数据为 JSON 用于分析

安装步骤

  1. 克隆仓库：git clone https://github.com/liaohch3/claude-tap.git
  2. 打开 Chrome → chrome://extensions → 开启开发者模式
  3. 点击「加载已解压的扩展程序」→ 选择仓库中的 extension/ 目录
  4. 访问 Claude.ai，点击扩展图标即可看到网络请求面板
⚠️
注意事项

Claude Tap 仅用于学习和调试目的。请遵守 Anthropic 的服务条款，不要用于批量抓取或商业用途。

• • •

4. Arize Phoenix — 本地可观测性

🌉
Arize Phoenix
开源 · 本地部署优先

本地优先的 LLM 应用可观测性和调试平台，提供 Prompt/Response 可视化对比、数据集管理、评测集成。

快速开始

# 安装
pip install ariz phoenix

# 启动 Phoenix
phoenix serve

# 在代码中集成追踪
from phoenix.trace.langchain import LangChainInstrumentor
LangChainInstrumentor().instrument()

# 运行你的 LLM 应用，访问 http://localhost:6006

核心特性

  • LLM 调用链路追踪（支持 LangChain / LlamaIndex / 原生）
  • Prompt/Response 可视化并排对比
  • Embedding 空间可视化（UMAP 降维）
  • 评测数据集管理与回放
  • 与 RAG 评估指标（Faithfulness 等）联动
官网 GitHub 文档
• • •

5. 其他调试工具速查

🪄
LangSmith
LangChain 官方平台，全生命周期端到端追踪（商业）
🔭
Helicone
开源 LLM 可观测性平台，替代 Langfuse 的轻量方案
🛠️
Portkey
LLM 网关 + 可观测性，统一接入多模型
🧬
OpenLIT
OpenTelemetry 原生 LLM 可观测性，轻量 SDK
🏹
PromptLayer
最早的 LLM 调试平台之一，侧重 Prompt 版本管理
🔌
Braintrust
面向开发者的 LLM 调试 + 评测平台
💡
工具选型建议

快速原型调试 → LLM Space（桌面级，所见即所得）
生产环境追踪 → Langfuse（全链路，支持自托管）
本地可视化分析 → Arize Phoenix（零成本，快速上手）
浏览器内调试 → Claude Tap / Similar Extensions
企业级方案 → LangSmith / Braintrust（商业，功能完善）