LangSmith 綁 LangChain、Helicone 只看 proxy：Langfuse v3 用 OpenTelemetry 把 LLM 追蹤搬回自家伺服器

LLM 應用一進入生產環境就會冒出讓人頭痛的問題：模型回應變慢、token 成本失控、輸出品質掉檔，但日誌看不出哪一步出狀況。傳統 APM 工具不認識 prompt、token、temperature 這些概念，把 LLM 呼叫當成普通 HTTP request 來記。LangSmith 雖然針對 LLM 設計，但只能 SaaS，企業資料外送不是每家公司都能接受，而且強烈綁定 LangChain，換框架就得重寫一遍 instrumentation。

Langfuse 一開始就走開源路線，2024 年底發布的 v3 把架構整個翻新，2026 年初被 ClickHouse 收購後仍維持 MIT 授權，主程式可以完整自架。對於有資料治理要求、或想精準掌握 LLM observability 成本的團隊來說，這是目前最完整的選擇。

v3 為何要拆成六支容器

Langfuse v2 把所有 trace 都塞進 PostgreSQL，跑到月流量幾百萬條後查詢延遲就崩了。算一個 dashboard 等好幾分鐘是常態，因為 PostgreSQL 的 row-store 設計天生不適合 OLAP 工作量。

v3 的核心改動是把 trace 儲存從 PostgreSQL 搬到 ClickHouse。ClickHouse 是 columnar 資料庫，跑 GROUP BY 聚合的速度是 PostgreSQL 的數十倍到上百倍。Trace 進來之後不直接寫資料庫，而是先丟到 S3 或 MinIO 物件儲存，只在 Redis 留一個指標進佇列。背景 worker 從 S3 撈出來再寫進 ClickHouse，把 ingestion 跟查詢負載完全切開。

完整部署一共六支容器：

• langfuse-web：UI 加 API，預設 3000 port
• langfuse-worker：背景工作處理器，跑 evaluation、queue consumer
• postgres：transactional 資料（使用者、專案、prompt 版本）
• clickhouse：trace 與 observation 的 OLAP 儲存層
• redis：佇列、快取、rate limiting
• minio：S3 相容物件儲存，放 trace payload 與匯出檔案

看起來元件偏多，但都是常見技術棧，運維熟悉度高。對於高吞吐場景（每天上千萬 trace），這個架構可以橫向擴展 worker 來消化壓力，不會卡在資料庫單點。

Docker Compose 部署

月處理量在百萬 trace 以下的團隊，單機 Docker Compose 就夠用。從官方倉庫下載 docker-compose.yml：

1
2

git clone https://github.com/langfuse/langfuse.git
cd langfuse

設定三組強制要求的環境變數：

1
2
3

export NEXTAUTH_SECRET=$(openssl rand -hex 32)
export SALT=$(openssl rand -hex 16)
export ENCRYPTION_KEY=$(openssl rand -hex 32)

寫進 .env 之後拉起服務：

1

docker compose up -d

打開瀏覽器到 http://your-server:3000，第一個註冊的帳號自動成為管理員。建立專案、產生一組 public/secret key pair，就可以開始接資料。

部署上要注意的是 ClickHouse 的儲存配置。預設的 Docker volume 直接放在主機檔案系統，跑大量寫入時 IO 會是瓶頸。VPS 環境下，把 ClickHouse 的 data volume 對應到 NVMe SSD 是必要的，否則延遲很快就會被磁碟拖垮。

OpenTelemetry 讓 SDK 不再是綁約

Langfuse v3 另一個關鍵設計是支援 OpenTelemetry Protocol。Trace 接收端是 /api/public/otel 這個 OTLP endpoint，意味著任何能輸出 OTLP 格式的工具都可以直接送資料進來，不需要寫專用 SDK。

這解決了 LLM observability 工具的長期痛點：每換一個語言就要重寫 SDK。Langfuse 用 OpenTelemetry 之後，Python、TypeScript、Go、Java、Rust 都可以用各自生態系成熟的 OTel SDK，加上 Langfuse 定義的 attribute schema 就能完整追蹤 LLM 呼叫。

以 Python 端整合 OpenAI SDK 為例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import base64
from openinference.instrumentation.openai import OpenAIInstrumentor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

LANGFUSE_AUTH = base64.b64encode(
    f"{PUBLIC_KEY}:{SECRET_KEY}".encode()
).decode()

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(
    endpoint="https://your-langfuse.example.com/api/public/otel/v1/traces",
    headers={"Authorization": f"Basic {LANGFUSE_AUTH}"},
)))

OpenAIInstrumentor().instrument(tracer_provider=provider)

從這一刻起，OpenAI SDK 的所有呼叫都會自動產出 OTLP span 送進 Langfuse。換成 Anthropic、Vercel AI SDK、LiteLLM、LangChain 的 instrumentation 都是同樣模式，沒有 vendor lock-in。

跨 span 傳遞共用 metadata（使用者 ID、session ID）建議用 OpenTelemetry Baggage 加 BaggageSpanProcessor，這是 OTel 標準機制，會自動把指定的 key-value 複製到同一條 trace 內的所有 span，不用手動在每個 span 重複塞屬性。

跟其他自架方案怎麼比

LLM observability 的自架選項不只 Langfuse 一個。實際比對下來，三個主要競爭者各有定位：

Arize Phoenix：純 OSS、跑 SQLite 或 PostgreSQL，部署最簡單，但缺 prompt management 跟自動 evaluation pipeline，比較像「能用就好」的入門選擇，適合做 PoC。

Helicone：架構乾淨、跑得起來，但定位是 LLM proxy 加觀測，所有流量都要經過它的 gateway。延遲多一跳、要在應用層改 base URL，企業端推動有阻力。

LangSmith：功能完整、UI 體驗最好，但只能用 SaaS，自架版本是企業合約綁定的，對中小團隊不友善。而且強烈綁定 LangChain，換框架等於放棄整套儀表板。

Langfuse 同時涵蓋 tracing、prompt 版本管理、自動 evaluation、dataset、playground 五個面向，完整自架，沒有框架綁定。代價是要多扛一點維運成本：六支容器、兩個資料庫。對於認真把 LLM 應用做進生產環境的團隊，這點工夫換來的彈性是划算的。

生產環境調校

實際上線之前有幾個設定要留意。

S3 的 lifecycle policy 要設好。Trace payload 進 S3 之後 ClickHouse 會把摘要寫進自己的儲存，但原始 payload 還留在 S3。沒設過期規則的話，三個月後光是 MinIO 的磁碟用量就會讓人想哭。建議 90 天移到 cold storage、180 天刪掉，視合規要求調整。

ClickHouse 的 part 合併要監控。寫入頻繁的場景下，ClickHouse 會產生大量小 part，靠背景 merge 合併。Merge queue 堆積會嚴重影響查詢效能，這是自架最容易踩雷的地方。指標可以從 ClickHouse 自帶的 system.parts 表查，或丟給 Prometheus exporter。

Worker 的擴容是線性的。Ingestion 撐不住時直接加 worker 容器數量就好，不用動 web。建議從 1 個 worker 起步，看 Redis 的 queue 長度趨勢決定要不要加。

PostgreSQL 跟 ClickHouse 的備份策略要分開規劃。PostgreSQL 用 pg_dump 或邏輯複製，ClickHouse 用 BACKUP 指令搭配 S3 是最簡單的做法。資料量大時 ClickHouse 的備份時間會明顯長於 PostgreSQL，rotate 策略要相應調整。

最後一個容易忽略的點是 NEXTAUTH_URL 跟 reverse proxy 的搭配。Langfuse 用 NextAuth 做認證，反向代理沒設正確的 host header，登入後 callback 會跳到內網 IP，瀏覽器直接卡死。Nginx 或 Caddy 設定務必把 X-Forwarded-Proto、X-Forwarded-Host 完整轉發。

LLM observability 跟自架 VPS 是天然契合的組合——資料敏感、流量不固定、需要彈性擴容。Langfuse v3 的六容器架構雖然複雜，但跑在搭載 NVMe SSD 的單台機器上就能撐月處理千萬等級的 trace。NCSE Network 提供臺灣本地的 Intel Gold CPU 加 NVMe SSD VPS，機房位於是方電訊，適合需要低延遲存取的 AI 應用觀測場景。詳細規格可到 ncse.tw 了解。