openlit/openlit · 上手攻略

  • 仓库：openlit/openlit
  • 链接：https://github.com/openlit/openlit
  • 分类：AI 工程平台 / LLM 可观测性 / Agent 评估
  • 作者：spark
  • 更新：2026-07-20

是什么

OpenLIT 是一个开源的 AI Engineering 平台，定位是"一站式把 LLM 应用从实验推到生产"。它把 OpenTelemetry 当作统一底座，向上提供 6 类核心能力：

  1. 可观测性 SDK（Python / TypeScript / Go）：对 50+ LLM provider、VectorDB、Agent 框架、GPU 做自动埋点（auto-instrumentation），一行业务代码就能开启 trace + metric。
  2. 11 种内置 LLM-as-Judge 评估：幻觉（hallucination）、偏见（bias）、毒性（toxicity）、安全性（safety）、指令跟随（instruction following）、完整性（completeness）、简洁性（conciseness）、敏感性（sensitivity）、相关性（relevance）、连贯性（coherence）、忠实性（faithfulness）。
  3. Guardrails 规则引擎：基于 trace 属性的 AND/OR 条件规则，命中时动态加载 prompt/上下文/评估配置。
  4. GPU 监控 + 异常仪表盘：抓取 GPU 利用率/显存/温度，结合 LLM 异常事件（OOM、超时）定位问题。
  5. Prompt Hub + Vault：prompt 版本管理、密钥集中托管。
  6. OpenGround Playground：并排对比多个 LLM。

它的核心卖点是 OTel-native：trace 使用 gen_ai.* semantic convention，可以不经 OpenLIT UI 直接落到 Datadog / Honeycomb / Grafana Tempo / 任意 OTel Collector，对已经用 OpenTelemetry 的团队几乎没有接入成本。

最近版本还新增了 CLI：给 Claude Code / Cursor / Codex 这类本地 coding agent 安装 vendor hooks，把 session / prompt / 工具调用 / 子 agent 派生都通过 OTel 输出，对应 OpenLIT dashboard 的 /coding-agents 视图。

解决什么问题

LLM 应用进入生产后，团队通常会撞到四类痛点：

  • 看不到钱烧在哪：一次请求多少 token、哪些 prompt 最贵、哪个用户最耗资源。
  • 看不到推理链路：RAG 哪一步检索出错、agent 哪一步卡住、哪个工具调用耗时异常。
  • 没有统一评估：模型换了、prompt 改了，效果是变好还是变差没法量化。
  • 散落的密钥与 prompt：每个服务都自己拼 API key，prompt 散在代码里，版本管理缺失。

OpenLIT 把这四件事收口成一个 SDK + 一个自托管 UI（Docker compose 一键起，后端 ClickHouse）。相对 Langfuse、Helicone、Arize Phoenix 这类"单点工具"，它的差异化在于：(a) 强 OTel 兼容，不绑定自家 UI；(b) 自带 LLM 评估而非只做 trace；(c) 把 GPU 监控也纳入同一个仪表盘。

快速安装

OpenLIT 拆成两部分：SDK（装在业务进程里）和 后端 UI（自托管）。

1) 拉起后端 UI（Docker）

git clone https://github.com/openlit/openlit.git
cd openlit
docker compose up -d

启动后浏览器访问 http://127.0.0.1:3000，默认账号：

  • Email：user@openlit.io
  • Password：openlituser

生产部署走 Kubernetes + Helm，参考 docs.openlit.io 的 kubernetes 安装指南。

2) 装 SDK

# Python
pip install openlit

# TypeScript（具体命令见 sdk/typescript 目录的 README）
npm i openlit

3) 一行代码接入

import openlit
openlit.init()  # 默认走 console 输出，dev 阶段方便看 trace

要落地到自托管 UI，加一行 OTLP endpoint：

import openlit
openlit.init(otlp_endpoint="http://127.0.0.1:4318")

或者用环境变量：

export OTEL_EXPORTER_OTLP_ENDPOINT="http://127.0.0.1:4318"

import openlit
openlit.init()

至此，OpenAI、Anthropic、Cohere、Mistral、Groq、Google AI Studio、Together、Ollama、AWS Bedrock、Azure AI Inference 等调用都会自动产生 trace。

核心用法

1) 自动埋点 OpenAI / Anthropic

只要在调用之前 openlit.init()，不需要改业务代码，OpenLIT 会拦截 SDK 拿到 prompt / response / token / latency。配合 OpenAI 的简单示例：

import openlit
import openai

openlit.init(otlp_endpoint="http://127.0.0.1:4318")

client = openai.OpenAI()
resp = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "用一句话解释 RAG"}],
)
print(resp.choices[0].message.content)

之后在 UI 的 Requests 页能看到该次调用的全链路 trace 和 cost。

2) 把 LangChain / LlamaIndex / VectorDB 也接进来

OpenLIT 对 LangChain、LlamaIndex、Chroma、Pinecone、Weaviate、Qdrant、Milvus 都做自动埋点。如果用了 RAG，retrieval 步骤会作为独立 span 出现在 trace 上，能直观看出"是检索没找到还是 LLM 没答好"。

3) 触发评估

有两种评估入口：

  • 在线评估：在 openlit.init 中配置 rule engine，让每次 trace 自动跑 LLM-as-Judge，命中规则的请求会打标签（hallucination=true 等）。
  • 离线批量评估：从历史 trace 抽样，跑 11 种内置 judge 之一，对比 prompt/模型切换前后的指标。

例如对一段历史 trace 跑 faithfulness：

from openlit.evals import evaluate

result = evaluate(
    trace_id="abc123",
    metric="faithfulness",  # 11 种之一
    context_source="retrieved_documents",
)
print(result.score, result.reasoning)

4) Coding Agent CLI（新增能力）

如果团队在用 Claude Code / Cursor / Codex 想看每个 session 的成本与操作轨迹：

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/openlit/openlit/main/cli/scripts/install.sh | sh

# 配置 OTLP 端点
openlit configure --endpoint http://127.0.0.1:4318

# 安装到所有 vendor
openlit coding install --vendor=all  # 也可指定 cursor / claude-code / codex

# 自检
openlit doctor

卸载：openlit coding uninstall --vendor=all。所有数据通过 coding_agent.* OTel 命名空间发出，可被任意 OTel Collector 接收。

5) 自定义成本（微调模型 / 自部署模型）

OpenLIT 自带主流 provider 的 token 单价。用了微调模型或自部署模型时，可以上传自定义 pricing JSON 让成本估算准确，路径在 UI 的 Settings → Cost Configuration。

典型适用场景

  • 多 provider 混合：同时用 OpenAI + Anthropic + 自部署 Llama，想统一看成本/延迟/质量。
  • RAG 上线后回归监控：trace + faithfulness/relevance 评估，发现"答非所问"的具体请求与上下文。
  • GPU 共享集群：多人共用推理 GPU，dashboard 看谁把显存吃满。
  • Coding agent 成本治理：Cursor/Claude Code 月底账单吓人时，按 session / prompt 维度拆解。
  • 不想被单一厂商锁定：坚持 OpenTelemetry 标准，未来想换 Datadog/Grafana 不需要重新埋点。

坑与注意

  • OTLP 端口默认 4318：业务进程要能访问到这个端口；compose 默认 127.0.0.1:4318，多机部署改成 collector 实际地址。
  • Auth 默认关闭：生产环境必须配 otlp_headers 或反向代理加 auth，否则 dashboard 是裸奔。
  • 资源占用：ClickHouse 后端对内存有要求，单机 demo ≥ 4 GB RAM 才能跑顺；生产建议 ≥ 16 GB 并加副本。
  • OTel 兼容性：底层依赖 OpenTelemetry SDK 版本，Python 3.8+ 都支持，但用了极旧版本 OTel 的项目可能要适配 opentelemetry-instrumentation-* 包。
  • 评估成本：LLM-as-Judge 本身会调用 LLM，11 种 judge 全开等于翻倍 token 消耗；建议先开 faithfulness + hallucination 两个最关键的，再按需加。
  • Prompt Hub 版本化：相比 LangSmith 的 prompt 版本管理，OpenLIT 的 Prompt Hub 是较新功能，UI 体验略粗糙，复杂场景考虑直接用 LangSmith 或自建。
  • 本地 console 输出只是 dev 辅助：不留存历史，仅作调试。

与同类对比

工具 定位 OTel 原生 内置 LLM 评估 GPU 监控 自托管 UI
OpenLIT 平台型 ✅ ✅ 11 种 ✅ ✅
Langfuse Trace + Eval 部分（OpenInference） ✅ ❌ ✅
Helicone 代理型观测 ❌ ✅ ❌ ✅
Arize Phoenix Eval / Drift 部分（OpenInference） ✅ ❌ ✅
LangSmith LangChain 一体化 ❌ ✅ ❌ ✅（闭源托管）
Datadog LLM Observability APM 厂商 ✅ 部分 ❌ 闭源托管

OpenLIT 的相对优势是 OTel 原生 + GPU 监控 + 评估三件套 + 自托管，在不想被 SaaS 绑定、又需要 LLM 评估的团队里是少见能凑齐的组合。相对劣势是：UI 比 LangSmith 简陋、Prompt 版本管理弱、ClickHouse 后端资源消耗偏高。

一句话推荐

如果团队已经在用 OpenTelemetry、需要把 LLM 应用 + GPU 一起管、又要自托管避免 SaaS 锁定，OpenLIT 是当下少数能一站式覆盖的开源方案；否则 Langfuse（更轻量）或 Arize Phoenix（评估更深）也值得并行评估。

不确定处

  • 文中 11 种内置评估类型与 OpenGround Playground 能力为 README 描述，未逐一在 docs 验证最新字段名；用前建议对照 docs.openlit.io/latest/sdk/features/evaluations。
  • "Coding Agent CLI" 为较新功能，命令细节来自 README 摘录，未实际执行；建议先 openlit doctor 做 dry run。
  • Stars / License / 最近提交数据来自仓库卡（2623★ / Apache-2.0 / 2026-07-17），访问 README 当下可能略有变化。