lmnr-ai/lmnr · 上手攻略

  • 仓库：lmnr-ai/lmnr
  • 链接：https://github.com/lmnr-ai/lmnr
  • 分类：ai
  • 作者：spark
  • 更新：2026-07-17

这是什么

Laminar（仓库路径 lmnr-ai/lmnr，官方域名 laminar.sh，品牌写作"Laminar"——注意跟流体力学的层流同名）是 为 AI Agent 量身打造的开源可观测性平台，由 YC S24 孵化的团队开发，Apache-2.0 协议，主仓 ~3.1k Stars、TypeScript/Rust 混合栈，最近一次 release 验证于 2026-06-18。

它用一句话概括：OpenTelemetry 原生的 tracing SDK，加一行代码就能自动跟踪 Vercel AI SDK、LangChain、OpenAI、Anthropic、Gemini、Browser Use、Stagehand 等主流框架，并在之上再加一层"LLM-native"的能力：自然语言写告警（Signals）、离线/在线评估（Evals）、自定义仪表盘（Dashboards）、给 Coding Agent 用 SQL/MCP 查 trace。

它跟 Langfuse / LangSmith / Phoenix / Arize 这类竞品处在同一品类，但定位差异很硬核：默认目标对象是 agent，不只是 prompt→response 的单次 LLM 调用，而是一段包含多次 LLM、工具调用、子 agent 委派的整条运行轨迹。

解决什么问题

AI agent 上生产后你会立刻撞到三件事，Laminar 想用同一套栈一锅端：

  1. trace 全链路：agent 跑了哪几步、每次 LLM 的 prompt/completion、工具 I/O、token、延迟、错误，得全采到。Laminar 用 OpenTelemetry 语义模型存 span，Rust 写的存储层号称"20× trace compression"以压缩写入和存储。
  2. 异常行为告警：不想为每一个 case 写硬编码监控规则。Signals 让你写一句英文 —— "agent 卡在循环里" / "超过 3 次工具调用还没收敛" —— Laminar 自动扫所有 run，符合条件就在 Slack @你。
  3. 评估 & 数据集：本地/CI 里跑 eval 集，UI 可视化对比、可标注、可导出做训练数据。用同一份 SDK 既写生产代码又跑 eval，不用切两套体系。

附带几个差异化卖点： - Coding Agent 集成：内置 MCP server + CLI，让 Claude Code / Codex 等 coding agent 直接用 SQL 查 trace，并基于 trace 自行 debug。 - Hosted + 自托管双模：不想运维就上 laminar.sh；想全私有就 docker compose up -d，UI 默认在 http://localhost:5667。 - 真·多语言 SDK：Python 装 pip install lmnr[all] 自动带 OpenAI/Anthropic 等 instrument；TS 装 npm add @lmnr-ai/lmnr 同理。

快速安装

方式一：托管平台（最快，零运维）

直接到 laminar.sh 注册，建 project，拿 LMNR_PROJECT_API_KEY。

方式二：本地自托管

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

UI 默认 http://localhost:5667。生产环境用 docker compose -f docker-compose-full.yml up -d。

方式三：只用 SDK 连接远端（或自托管实例）

Python

pip install --upgrade 'lmnr[all]'   # 一并装所有 instrumentation 插件

TypeScript / Node

npm add @lmnr-ai/lmnr              # 含 OpenAI / Anthropic / LangChain 等 instrument

⚠️ 包名是 @lmnr-ai/lmnr（全小写有连字符），不是 @lmnr/laminar、也不是 laminar。

关键配置

把 backend 起好后，需要给 SDK 指过去：

from lmnr import Laminar, observe
Laminar.initialize(project_api_key="<LMNR_PROJECT_API_KEY>")
# 可选，自托管时指向本机：
# Laminar.initialize(project_api_key="...", base_url="http://localhost:5667")

Laminar 还内置一些 server-side AI 能力（chat-with-trace、SQL-with-AI），需要 LLM provider，复制 .env.example 到 .env 后填一份：

# 方案 A：Gemini
LLM_PROVIDER=gemini
LLM_API_KEY=你的Gemini key

# 方案 B：OpenAI 兼容网关（含 vLLM / OpenRouter / LiteLLM）
LLM_PROVIDER=openai
LLM_BASE_URL=http://localhost:4000   # 可选
LLM_API_KEY=你的key

# 方案 C：AWS Bedrock（Anthropic Claude）
LLM_PROVIDER=bedrock
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=us-east-1

可选地指定 small/medium/large 三档模型，让不同任务用不同尺寸。

关闭匿名遥测：自托管默认会上报匿名使用统计，关掉就 LAMINAR_TELEMETRY_DISABLED=true。

核心用法

1. 一行代码自动 trace LLM 调用

只要初始化过 Laminar.initialize(...)，后续对 OpenAI/Anthropic/LangChain 等标准 SDK 的调用会被自动 instrument：

import os
from openai import OpenAI
from lmnr import observe, Laminar

Laminar.initialize(project_api_key=os.environ["LMNR_PROJECT_API_KEY"])

client = OpenAI()

@observe()
def poem_writer(topic: str) -> str:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": f"写一首关于{topic}的诗"}],
    )
    return resp.choices[0].message.content

print(poem_writer(topic="层流"))

跑一遍，UI 的 Traces 页就该出现一条包含 LLM span 的记录。

2. 用 observe / @observe 包任意函数

自动 instrument 只覆盖标准 LLM/工具调用，业务函数用 @observe() 自己包，IO、参数、返回值都被采：

@observe(name="retrieve_docs")
def retrieve(query: str, k: int = 5):
    return vector_db.search(query, top_k=k)

@observe()
def rag_answer(question: str) -> str:
    docs = retrieve(question)
    ctx = "\n\n".join(d.page_content for d in docs)
    return client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role":"user","content":f"基于：{ctx}\n回答：{question}"}],
    ).choices[0].message.content

UI 上能看到 rag_answer → retrieve_docs → openai.chat 完整嵌套。

3. Signals：用自然语言定义异常

在 UI 里（或者用 SDK）写一句：

"agent 调用 tool 超过 5 次还没回答"

或者：

"response 里包含 'I don't know'"

Laminar 后台扫历史 + 实时 run，命中就 Slack 通知。

4. Evals：跑离线/在线评估

  • 本地用 SDK 跑 eval 集、跑 CI；
  • CLI 直接触发：npx @lmnr-ai/cli eval run ...（见 docs）；
  • UI 里看分数分布、对比两轮实验、导出新的标注数据集。

5. Coding Agent 查 trace

配好 MCP server 后，Claude Code / Codex 会自然地用 SQL 查 trace：

SELECT name, duration, attributes->>'input'
FROM spans
WHERE trace_id = '...' AND span_type = 'llm'
ORDER BY start_time;

等於把 trace 数据直接喂给 agent 当 runtime debug 工具。

6. Dashboard 自定义 SQL

Dashboards docs：用 SQL 查 spans/events/metrics，可视化拼装自定义面板，适合接 Grafana 习惯的人。

典型适用场景

  • 生产环境 AI agent 监控：客服 agent、coding agent、workflow agent 都需要看到每一步，挂了能复盘。
  • Eval & A/B 测试：同一组 prompt 在两个模型 / 两套参数下批量比对，不要人肉挑。
  • 数据标注→训练集：把线上真实 trace 挑出来打标，导出 JSONL 喂微调流程。
  • Coding agent 调试循环：让 coding agent 直接查自己产生的 trace，"自描述"地找 bug。Laminar 的 MCP server 是这一场景的强卖点。

坑与注意

  • 使用量计费路径：托管平台是按 trace 量 / eval 次数收费（详见 laminar.sh 官网 pricing），大规模上生产前确认预算；自托管没有这层限制。
  • trace 体积与采样：高频在线时建议先开 head sampling，把 100% 跑满容易撑爆 Postgres。docker compose-full.yml 默认是单机配置，单实例写穿 QPS 约数百到数千，多 tenant / 多 region 场景需要 lmnr-helm chart 上 K8s。
  • schema 隔离：默认 public schema，跟其他 Drizzle 项目同库会冲突。改 POSTGRES_SCHEMA=laminar，并视情设置 POSTGRES_CREATE_SCHEMA=false。
  • required port：默认 UI 5667、gRPC 端口另外开，记得放过防火墙；如果走自托管 + 远端 SDK，base_url 要指向能通的域名/IP。
  • SDK 升级：Python 的 [all] extra 包会拉很多 instrument 库，CI 里要锁版本；TypeScript 同理，定期 npm audit。
  • Signals 的判定边界：自然语言告警准确率由 LLM 决定，初期会有误报 / 漏报，建议先在离线 trace 上回放调阈值再上线。

与同类对比

维度 Laminar Langfuse LangSmith Phoenix (Arize)
License Apache-2.0 MIT 闭源，部分开源 Apache-2.0
自托管 ✅ docker compose + Helm ✅ docker compose ❌ ✅ docker compose
协议 OpenTelemetry 原生 OpenTelemetry 自有 + OTEL 兼容 OpenInference
Agent 优先 是 否（但支持） 否 否（LLM 优先）
Coding Agent MCP ✅ ❌ ❌ ❌
Eval SDK + CLI + UI SDK + UI SDK + UI UI 强
存储引擎 Rust 自研（20× 压缩） Postgres + ClickHouse 闭源 Postgres
自然语言告警 Signals Alerting（规则） Alerting Drift

总结：如果你团队大量跑 agent（不是单 LLM 调用）、想 自托管 + 可控成本、且打算让 coding agent 自己查 trace debug，Laminar 是当前最贴合的一档；如果只在 prompt-completion 单步调用阶段，Langfuse/Phoenix 已经够用也成熟。

一句话推荐

Agent 时代最值得先试的自托管 OTEL-native 可观测性栈 —— 多装一行，agent 上线后能看见、能告警、能训。

具体动作：托管先用 laminar.sh 建 project → pip install lmnr[all] 或 npm add @lmnr-ai/lmnr → Laminar.initialize(...) 跑一遍现有 demo，打开 UI 看一眼 trace；顺手把 docker compose up -d 起一份本地副本，方便后续切自托管。