Spanlens

综合介绍

Spanlens 是一个面向开发者的开源可观测性工具，专门用来监控大语言模型（LLM）的调用情况。它解决了一个很实际的问题：当你的应用接入了 OpenAI、Anthropic、Gemini 或 Ollama 这些模型服务后，每次请求花了多少钱、耗时多久、用了多少令牌，这些数据往往难以统一查看。

Spanlens 的做法很简单。你不需要修改应用代码，只需要把 baseURL 切换成 Spanlens 提供的地址，它就能自动记录下每一次模型调用的详细信息。这个工具支持自托管部署，数据完全掌握在自己手中，没有第三方服务介入。

项目采用 MIT 许可证，意味着你可以自由使用、修改甚至商用。对于正在开发 LLM 应用、关心调用成本和性能的团队来说，Spanlens 提供了一个轻量且透明的监控方案。

功能列表

1. 一行切换 baseURL：只需修改配置中的 baseURL 地址，即可接入监控，无需改动业务代码。
2. 多提供商支持：兼容 OpenAI、Anthropic、Gemini、Ollama 等主流 LLM 服务。
3. 成本追踪：自动计算每次调用的费用，帮助控制预算。
4. 延迟分析：记录请求响应时间，便于定位性能瓶颈。
5. 令牌统计：展示输入和输出令牌数量，辅助优化提示词。
6. 代理轨迹记录：追踪请求的完整链路，便于排查问题。
7. 自托管部署：可部署在自己的服务器上，保障数据隐私。
8. 开源免费：采用 MIT 许可，源码公开，可自由定制。

使用帮助

安装与部署

Spanlens 是自托管工具，你需要将它部署在自己的服务器或本地环境中。它提供了 Docker 镜像，这是最快捷的部署方式。

首先，确保你的机器上安装了 Docker。然后执行以下命令拉取镜像并启动服务：

docker run -d -p 4000:4000 spanlens/spanlens

这条命令会把 Spanlens 服务运行在 4000 端口。你可以根据实际需要修改端口映射。启动后，通过浏览器访问 http://localhost:4000 即可看到控制台界面。

如果你希望数据持久化，可以挂载一个数据卷：

docker run -d -p 4000:4000 -v spanlens-data:/app/data spanlens/spanlens

这样监控数据会保存在 Docker 卷中，即使容器重启也不会丢失。

配置模型提供商

Spanlens 支持 OpenAI、Anthropic、Gemini 和 Ollama 四类提供商。你需要在控制台中添加对应的 API 配置。

登录控制台后，找到"设置"或"Providers"页面。点击添加提供商，选择类型，然后填入你的 API Key 和默认模型参数。对于 Ollama，你只需要填写 Ollama 服务的地址，例如 http://localhost:11434。

配置完成后，Spanlens 会生成一个专属的 baseURL。这个地址格式通常是 http://你的服务器地址:4000/v1。把这个地址记下来，下一步会用到。

接入你的应用

这一步是整个工具的核心操作。在你的 LLM 应用代码中，找到初始化客户端的部分。以 OpenAI Python 客户端为例：

from openai import OpenAI

client = OpenAI(
    api_key="你的API Key",
    base_url="http://你的服务器地址:4000/v1"
)

你只需要把 base_url 修改为 Spanlens 提供的地址，其他代码完全不用动。如果使用 Anthropic 的 SDK，设置 base_url 的方式类似。

对于使用 Ollama 的情况，把 Ollama 的 endpoint 指向 Spanlens 即可。例如：

ollama_client = Ollama(base_url="http://你的服务器地址:4000")

切换完成后，你的应用发起的每一次模型请求都会先经过 Spanlens，再由它转发给真实的模型服务。这个过程对应用是透明的，响应结果不会受到任何影响。

查看监控数据

回到 Spanlens 控制台，你会看到仪表盘页面。这里展示的是所有请求的汇总信息，包括总请求数、平均延迟、总花费等。

在请求列表页面，你可以看到每一条请求的详细记录。点击任意一条记录，会展开完整的信息：

• 请求时间与耗时
• 使用的模型名称
• 输入和输出的令牌数量
• 本次调用的费用
• 完整的请求和响应内容

代理轨迹功能会展示这条请求从进入到返回的完整路径，包括中间经过的每次转发。这对于排查请求异常或理解链路耗时非常有帮助。

控制台还提供了筛选功能。你可以按提供商、模型名称、时间范围等条件过滤记录，快速找到关心的数据。

日常维护

Spanlens 的日常维护比较简单。由于是自托管，你需要关注服务器的磁盘空间，因为请求日志会持续增长。建议定期查看数据卷的使用情况，必要时清理旧日志。

升级版本时，拉取最新的 Docker 镜像并重新创建容器即可。配置和数据都会保留。

产品特色

通过一行 baseURL 切换，即可实现对主流 LLM 调用的成本、延迟、令牌和代理轨迹的全面观测。

适用人群

• LLM 应用开发者：需要了解每次模型调用的费用和性能数据，优化应用表现。
• AI 产品团队：监控生产环境的模型调用情况，确保服务稳定并控制成本。
• 技术管理者：通过数据了解团队 AI 资源使用情况，辅助决策。
• 开源爱好者：喜欢研究和使用开源工具，愿意参与项目改进。

应用场景

• 开发调试阶段：接入 Spanlens 后，可以清楚看到每次请求的令牌消耗和延迟，快速定位提示词设计中的问题。
• 生产环境监控：实时掌握模型服务的健康状态，及时发现异常延迟或错误。
• 成本控制：按月查看不同模型、不同业务线的调用费用，找出成本热点并优化。
• 多模型对比：同时接入多个提供商，对比它们在相同任务上的性能和价格，选择最合适的方案。

常见问题

• Spanlens 支持哪些模型提供商？

目前支持 OpenAI、Anthropic、Gemini 和 Ollama。其他提供商如果兼容 OpenAI API 格式，也可以通过配置接入。

• 切换 baseURL 会影响请求速度吗？

会有轻微的网络开销，因为请求多经过一层转发。但 Spanlens 本身处理速度很快，对整体延迟影响很小。

• 数据安全如何保障？

Spanlens 是自托管工具，所有数据存储在你自己的服务器上。它不会主动向外部发送任何数据。

• 可以多人同时使用吗？

可以。Spanlens 没有限制并发用户数。团队内共享一个部署实例，大家都能查看监控数据。

• MIT 许可意味着什么？

你可以自由使用、修改、分发这个软件，甚至用于商业用途。只需要保留原始的版权声明。