1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | graphsignal-profiler |
| 作者/维护者 | Graphsignal, Inc.（官方仓库，GitHub API 确认） |
| 来源链接 | https://github.com/graphsignal/graphsignal-profiler |
| 许可证 | Apache-2.0（GitHub API） |
| GitHub Stars | 241（GitHub API） |
| Forks | 12（GitHub API） |
| 最新版本 | v0.20.4（GitHub tags，2026-07-21） |
| 安装方式 | uv tool install 'graphsignal[cu12]' 或 pip install 'graphsignal[cu12]' |
2. 功能介绍与亮点
graphsignal-profiler 教会 agent 为大模型推理服务接入 Graphsignal 的生产级性能画像平台。核心能力：
- 持续、高分辨率的性能时间线：暴露推理工作负载中各操作的耗时与资源占用
- LLM 生成链路追踪：逐步耗时、token 吞吐、延迟拆解，覆盖主流推理框架
- 系统级指标：CPU、GPU 及其他加速器的硬件层指标
- 错误监控：捕获设备级故障与推理错误
- AI 辅助优化：自动引擎调参（
--auto-flags）、在 Graphsignal 面板内用对话方式排查瓶颈，以及graphsignal-context让 Claude Code / Codex / Gemini 等 agent 直接在 IDE 内读取并分析性能数据
亮点：官方出品且持续维护（最近一次提交在近期内）、通过 CUPTI 以旁路进程方式采集 GPU 数据（不与 CUDA 共享进程）、对 vLLM、SGLang、PyTorch、dstack 均有开箱即用的自动埋点。
3. 适用场景
所属分类：DevOps 与基础设施
适合部署、运维大模型推理服务的工程师：定位 GPU 利用率瓶颈、比较不同引擎/硬件配置下的延迟与吞吐、在生产环境中持续追踪推理错误与设备故障。典型场景是给 vLLM/SGLang 服务加一行 graphsignal-run 前缀即可获得性能画像，无需改动业务代码。
4. 跨 Agent 兼容性
- Claude Code：原生支持。SKILL.md 采用标准 Agent Skills 格式，且官方文档明确点名
graphsignal-context功能支持 Claude Code 在 IDE 内直接读取性能数据 - Codex：原生支持。同一处官方文档同样将 Codex 列为
graphsignal-context的受支持 agent - OpenClaw：未验证。抓取到的材料中未提及
- Hermes Agent：未验证。抓取到的材料中未提及
5. 推荐理由
大模型推理服务的性能问题（GPU 利用率低、显存瓶颈、引擎参数不合理）通常缺乏直观工具定位，人工调参费时费力。graphsignal-profiler 把生产级 profiling 能力封装成一条命令，并且明确支持 agent 直接读取分析结果、给出调参建议，让 Claude Code / Codex 用户在优化推理服务时少走弯路。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | GitHub 241 stars、12 forks；公开 issue 中有 3 位独立外部用户报告过真实使用问题；未检索到第三方平台的独立评测或讨论 |
| 可用性 | 8 | uv tool install 或 pip install 一条命令即可安装，SKILL.md 对 vLLM/SGLang/PyTorch/dstack 分别给出可直接复制的命令；需注册免费账号获取 API key，属轻度配置；近期仍在持续发版 |
| 安全性 | 8 | 见下方检查清单 |
安全检查清单：
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | graphsignal-run 包裹推理服务启动命令，用途明确（无侵入式篡改） |
| ② 运行时联网外发 | 是——仅向 api.graphsignal.com 上传性能遥测数据，官方文档明确声明不采集 prompt/completion 等内容 |
| ③ API key / 凭据存储 | 需要 GRAPHSIGNAL_API_KEY 环境变量，官方账号体系签发，存储方式（环境变量）清晰可查 |
| ④ 可疑指令 | 未发现 prompt injection 或隐蔽指令 |
| ⑤ 作者信誉 | Graphsignal, Inc. 自 2021 年持续运营至今，无刷星等造假迹象 |
| ⑥ License | Apache-2.0，明确 |
| ⑦ 维护时间 | 近期仍有提交与发版，非弃置项目 |
综合 = 三项均值 = 8.33
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与 graphsignal-profiler 的差异 |
|---|---|---|
Datadog APM（dd-apm-datadog-labs-agent-skills） |
通用应用性能监控，覆盖全栈服务的 trace/metric/log | 面向通用后端服务，不专精 GPU/CUDA 级指标；graphsignal-profiler 专注推理引擎与加速器层面的深度画像 |
Arize AI Trace（arize-trace-arize-ai-arize-skills） |
LLM 应用可观测性，侧重评测、trace 与质量分析 | 关注模型输出质量与调用链，不做 CUPTI 级别的 GPU 硬件画像；graphsignal-profiler 更贴近推理服务的底层性能优化 |
两者都能与 agent 协同排障，但 graphsignal-profiler 的差异化在于面向“推理引擎 + GPU 硬件”这一更底层的性能层，而不是应用调用链或模型输出质量。
8. 用户评价
该技能目前在第三方平台（Reddit、Hacker News 等）尚无公开的具名用户评价；GitHub 仓库的 issue 区有 3 位独立开发者报告过实际使用中遇到的问题（均已关闭），可视为真实使用的间接佐证。
9. 其他补充
PyPI 上的 graphsignal 包发版历史可追溯至 2020 年 7 月，早于当前 GitHub 仓库的创建时间，说明该产品线本身运营时间更久。
10. 安装使用方式
# 安装（推荐：独立 uv 工具环境，避免污染推理服务的依赖）
UV_TOOL_BIN_DIR=/usr/local/bin uv tool install 'graphsignal[cu12]' # CUDA 12.x
# 或
UV_TOOL_BIN_DIR=/usr/local/bin uv tool install 'graphsignal[cu13]' # CUDA 13.x
# 使用：包裹推理服务启动命令
export GRAPHSIGNAL_API_KEY=<你的API key>
graphsignal-run vllm serve <model> --port 8001注意事项：需先在 graphsignal.com 注册免费账号获取 API key；若 graphsignal.watch() Python API 方式接入，需将包安装进被观测应用自身的环境（而非独立 uv 工具环境）；使用防火墙/代理环境时需放行 https://api.graphsignal.com 出站连接。
11. 注意事项
- 需要联网上传遥测数据到 Graphsignal 云端，无法完全离线使用
- OpenTelemetry 链路追踪需要在推理引擎自身的环境中另装
opentelemetry-sdk等依赖，独立 uv 工具环境无法自动提供 - 跨 Agent 兼容性仅确认 Claude Code 与 Codex，OpenClaw 与 Hermes Agent 未验证