langwatch/langwatch · 上手攻略

仓库：langwatch/langwatch
链接：https://github.com/langwatch/langwatch
分类：agent · llm-infra
作者：Tom
更新：2026-07-09

它是什么

LangWatch 是一个开源 LLMOps 平台，专注于 LLM 应用的全链路可观测性、评估测试与 Agent 仿真。官方定位是"AI 应用的 ops missing piece"——帮助团队在不自己造轮子的情况下，实现追踪（Trace）→ 数据集（Dataset）→ 评测（Evaluate）→ 优化（Optimize）的完整闭环。

核心能力分为四大模块：

可观测性（Observability）：追踪每一次 LLM 调用、Tool 使用和用户交互，自动生成带详细 Span 的 Trace，聚合为 Thread（用户会话）。
评测（Evaluations）：离线评测与生产环境实时评测结合，支持自定义评测指标和 Guardrails。
Agent 仿真（Simulations）：用真实场景模拟器对 Agent 做端到端回归测试，不必等到生产才发现问题。
Prompt 管理（Prompt Management）：版本化、Git 集成、链路追踪（版本→Traces）。

此外还有 AI Gateway（OpenAI/Anthropic 兼容代理，含虚拟 key、预算控制、路由降级）和 AI Governance（企业级合规架构，GDPR/ISO 27001 认证）。

解决什么问题

构建 AI 应用时，开发团队通常面临三个盲区：

不知道 AI 为什么会这样：LLM 调用黑箱，出问题无法定位到具体是 Prompt、Model 还是 Tool 的问题。
没有可靠的质量基准：改了一版 Prompt，不知道质量变好还是变差，没有数据支撑。
发布前无法系统性验证：Agent 在真实场景中会触发哪些边界 case，完全靠运气发现。

LangWatch 通过全链路 Tracing、离线评测环境和端到端仿真器，让团队在发布前就能系统地发现和修复问题，并在生产环境中持续监控。

快速安装

本地一键启动（推荐，无需 Docker）

只需 Node.js（18+），一行命令起完整本地环境（含 PostgreSQL、Redis、ClickHouse、OpenSearch）：

npx @langwatch/server

首次运行会自动在 ~/.langwatch/ 下安装依赖、生成 .env 配置，然后并行启动所有服务，打开 http://localhost:5560 。

清理重置：

rm -rf ~/.langwatch/

Docker Compose 部署

git clone https://github.com/langwatch/langwatch.git
cd langwatch
cp langwatch/.env.example langwatch/.env
docker compose up -d --wait --build

服务地址同样为 http://localhost:5560 。

Kubernetes Helm Chart

helm repo add langwatch https://charts.langwatch.ai
helm install langwatch langwatch/langwatch -n langwatch --create-namespace

在线 Saas（零基础设施）

直接访问 https://app.langwatch.ai 注册，最适合快速体验。

核心用法

第一步：创建项目，获取 API Key

登录后创建 Organization 和 Project，在 Settings → API Keys 创建服务 Key，获得两个环境变量：

LANGWATCH_API_KEY="sk-lw-..."
LANGWATCH_PROJECT_ID="your-project-id"

本地开发推荐用 CLI 登录，自动写入 .env：

npx langwatch login

第二步：安装 SDK

Python：

pip install langwatch
# 或
uv add langwatch

Node.js/TypeScript：

npm install langwatch @vercel/otel @opentelemetry/api-logs @opentelemetry/instrumentation @opentelemetry/sdk-logs

第三步：初始化并接入 Tracing

Python（以 OpenAI 为例）：

import langwatch
import os
from langwatch.instrumentors import OpenAIInstrumentor

langwatch.setup(
    api_key=os.getenv("LANGWATCH_API_KEY"),
    project_id=os.getenv("LANGWATCH_PROJECT_ID"),
    instrumentors=[OpenAIInstrumentor()]
)

# 之后的 OpenAI 调用会自动被追踪
response = openai.ChatCompletion.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

Node.js（Next.js 示例）：

在 next.config.js 开启 instrumentation hook，然后在 src/instrumentation.ts 中注册 LangWatch Exporter，具体见上方文档（链接）。

第四步：接入 LangChain / LangGraph / CrewAI 等框架

LangWatch 对主流框架有官方集成，在文档页面找到对应集成说明，主要也是通过 langwatch.setup() + 对应 Instrumentor 实现零改动追踪：

LangChain / LangGraph：加 LangChainInstrumentor()
CrewAI：加 CrewAIInstrumentor()
Vercel AI SDK：配置 experimental_telemetry: { isEnabled: true }

第五步：创建评测（Evaluations）

在 LangWatch Dashboard 中创建 Dataset（测试集），然后定义评测指标（如准确率、幻觉率、响应延迟），SDK 会自动把每次调用结果与评测指标关联。

第六步：Agent 仿真（Simulations）

在 Dashboard 中新建 Scenario，定义用户模拟器（user simulator）、工具集（tools）、状态（state）和 Judge（评判器），运行后查看 Agent 在每一步的决策路径，找出问题节点。

典型适用场景

场景	为什么用 LangWatch
发布前回归测试	用仿真器跑大量边界场景，确保 Prompt 改动不引入新问题
生产环境可观测性	全链路追踪所有 LLM 调用，快速定位异常
多模型对比评测	同一数据集在 GPT-4o / Claude / Gemini 上的表现对比
Agent 调试	可视化每个 Tool Call 的输入输出，定位 Agent 行为异常
Prompt 版本管理	Git 集成 + 版本→Traces 链路追踪，清楚每次改动的实际影响
合规要求高的企业	GDPR/ISO 27001 认证，支持私有化部署和混合部署

坑与注意

Service Key 需要 project_id：个人 Key（CLI login 生成）不需要 Project ID，但 Settings 页面创建的服务 Key 必须同时设置 LANGWATCH_PROJECT_ID，否则数据无法写入。
本地一键启动依赖 Node.js：如果 Node 版本低于 18，npx @langwatch/server 可能失败，建议用 nvm 切换。
企业模块不开源：Apache 2.0 协议覆盖核心开源部分，但 SCIM、审计日志、License 计费等企业模块（langwatch/ee/）需要商业授权。
SDK 分语言许可不同：核心 SDK（typescript-sdk、python-sdk、mcp-server）为 MIT，但整体仓库为 Apache 2.0，贡献代码前注意 CLA 流程。
ClickHouse 资源消耗：本地一键启动会启动 ClickHouse，在资源紧张机器上可能影响性能，建议配合 Docker 资源限制使用。

与同类对比

方案	特点	对比 LangWatch
LangSmith	OpenAI 官方生态，功能完整	闭源，定价高；LangWatch 开源自托管成本低
Phoenix（Arize）	聚焦可观测性和 RAG 分析	无仿真器；LangWatch 覆盖更全
Weave（Weights & Biases）	实验跟踪起家，LLM 支持后加	更偏研究场景；LangWatch 更偏 Agent 工程化
Custom + OpenTelemetry	自己搭 Tracing	建设成本高，无法开箱即用仿真和评测
LangWatch	全链路开源，仿真+评测+Gateway 一体	较新（2024-2025），社区生态仍在增长

一句话推荐结论

如果你需要一套开源、一体化、同时覆盖"发布前仿真测试"和"生产可观测性"的 LLMOps 平台，LangWatch 是目前 Star 增长最快的选手之一，3000+ Stars 的体量正处爆发期，值得押注。