feat(observability): integrate Langfuse for LLM token tracking and tracing
Closes #620 #497. Add opt-in Langfuse observability covering all five model types (chat, embedding, rerank, VLM, ASR) with HTTP-request-scoped traces and Docker Compose support (both cloud and self-hosted). Core package internal/tracing/langfuse: - HTTP client with batched async ingestion (non-blocking in request path) - Sampling, environment / release tagging, and graceful fallback when LANGFUSE_* env vars are absent (wrappers become no-ops) - Gin middleware opens one trace per traced request and finishes it after the handler chain returns, attaching method / path / user / session - Trace context is stored under a typed key exported from internal/types so logger.CloneContext can preserve it across handler / goroutine boundaries (otherwise each LLM call auto-created an orphan trace, fragmenting one request into many) Per-model generation wrappers (opt-in via NewChat/NewEmbedder/...): - chat: captures prompt, streaming output, token usage + TTFT - embedding: approximates tokens when the provider omits usage - rerank: previews query/docs, summarizes results to keep payload small - vlm: records image count and total bytes, never uploads raw pixels - asr: records file size and audio duration, never uploads audio bytes Async title generation (GenerateTitleAsync) now forwards the trace key into the goroutine so title calls appear under the parent chat trace. Docker Compose: - LANGFUSE_* env passthrough on the `app` service for cloud deployments - Optional `langfuse` profile spins up a self-hosted Langfuse stack that reuses WeKnora's existing PostgreSQL (separate database via an idempotent init container that fixes ICU collation drift) and Redis (separate DB number), adding only ClickHouse, MinIO, web and worker containers - web/worker entrypoints URL-encode DB_PASSWORD / REDIS_PASSWORD at start to avoid Prisma P1013 when passwords contain @ / # / etc. Docs: docs/Langfuse集成.md covers cloud vs self-hosted, per-model usage strategy, code map, and resource footprint.
This commit is contained in:
@@ -18,6 +18,88 @@ GIN_MODE=release
|
||||
# 可选值:true(自动放在 LOG_PATH 同目录下 llm_debug.log)、false/空(关闭)、或指定文件路径
|
||||
# LLM_DEBUG_LOG=true
|
||||
|
||||
# ========== Langfuse 可观测性(可选) ==========
|
||||
# 用于追踪 chat / embedding / rerank / VLM / ASR 模型调用,统计 token 消耗。
|
||||
# 详细说明:docs/Langfuse集成.md
|
||||
#
|
||||
# 方案 A:接入 Langfuse Cloud(最简单)
|
||||
# 1) 登录 https://cloud.langfuse.com 生成 API Key
|
||||
# 2) 填入下方 PUBLIC_KEY / SECRET_KEY
|
||||
# 3) docker compose up -d app
|
||||
#
|
||||
# 方案 B:自建 Langfuse(局域网/内网环境)
|
||||
# 1) 启动自建栈:docker compose --profile langfuse up -d
|
||||
# 首次启动后 ClickHouse 迁移约 1-2 分钟,耐心等待 langfuse-web 健康
|
||||
# 2) 浏览器打开 http://localhost:3000 注册管理员账号并生成 API Key
|
||||
# 3) 取消注释下方 LANGFUSE_HOST=http://langfuse-web:3000
|
||||
# 填入刚生成的 PUBLIC_KEY / SECRET_KEY
|
||||
# 4) docker compose up -d app
|
||||
#
|
||||
# 只要同时设置了 PUBLIC_KEY + SECRET_KEY 就会自动启用,无需显式开关。
|
||||
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxx
|
||||
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxx
|
||||
LANGFUSE_HOST=http://langfuse-web:3000
|
||||
# 自建模式下改成:LANGFUSE_HOST=http://langfuse-web:3000
|
||||
#
|
||||
# 可选:显式开关(true/false,默认根据 key 自动判断)
|
||||
# LANGFUSE_ENABLED=true
|
||||
# 可选:版本 / 环境标签,便于在 Langfuse UI 过滤
|
||||
# LANGFUSE_RELEASE=v0.4.2
|
||||
# LANGFUSE_ENVIRONMENT=production
|
||||
# 可选:批量上报与采样策略(生产高流量建议调大 FLUSH_AT、降低 SAMPLE_RATE)
|
||||
# LANGFUSE_FLUSH_AT=15
|
||||
# LANGFUSE_FLUSH_INTERVAL=3s
|
||||
# LANGFUSE_QUEUE_SIZE=2048
|
||||
# LANGFUSE_REQUEST_TIMEOUT=10s
|
||||
# LANGFUSE_SAMPLE_RATE=1.0
|
||||
# LANGFUSE_DEBUG=false
|
||||
|
||||
# ========== Langfuse 自建栈配置(仅在使用 --profile langfuse 时需要) ==========
|
||||
# 设计说明:为了最小化资源占用,Langfuse 自建栈会**复用** WeKnora 已有的
|
||||
# - postgres:创建独立的 "langfuse" 数据库(由 langfuse-db-init 容器一次性创建)
|
||||
# - redis :使用独立的 Redis DB 号(默认 1,WeKnora 用 0)
|
||||
# 真正新增的只有 3 个常驻容器:langfuse-web、langfuse-worker、langfuse-clickhouse
|
||||
# + 1 个专用 S3:langfuse-minio
|
||||
# + 1 个一次性 init:langfuse-db-init
|
||||
#
|
||||
# Langfuse Web UI 对外端口
|
||||
# LANGFUSE_WEB_PORT=3000
|
||||
#
|
||||
# Langfuse 专用 MinIO 端口(避免和 WeKnora 主 MinIO 9000/9001 冲突)
|
||||
# LANGFUSE_MINIO_S3_PORT=9100
|
||||
# LANGFUSE_MINIO_CONSOLE_PORT=9101
|
||||
#
|
||||
# 在 WeKnora-postgres 中创建的 Langfuse 库名
|
||||
# LANGFUSE_DB_NAME=langfuse
|
||||
#
|
||||
# 在 WeKnora-redis 中使用的 DB 号(1~15,不要和 WeKnora 的 0 冲突)
|
||||
# LANGFUSE_REDIS_DB=1
|
||||
#
|
||||
# ClickHouse / Langfuse 专用 MinIO 凭证(生产请务必修改)
|
||||
# LANGFUSE_CLICKHOUSE_USER=clickhouse
|
||||
# LANGFUSE_CLICKHOUSE_PASSWORD=clickhouse
|
||||
# LANGFUSE_MINIO_USER=langfuseminio
|
||||
# LANGFUSE_MINIO_PASSWORD=langfuseminiosecret
|
||||
#
|
||||
# Langfuse 核心安全字段,生产必须重新生成:
|
||||
# LANGFUSE_SALT=$(openssl rand -base64 32)
|
||||
# LANGFUSE_ENCRYPTION_KEY=$(openssl rand -hex 32)
|
||||
# LANGFUSE_NEXTAUTH_SECRET=$(openssl rand -base64 32)
|
||||
# LANGFUSE_SALT=
|
||||
# LANGFUSE_ENCRYPTION_KEY=
|
||||
# LANGFUSE_NEXTAUTH_SECRET=
|
||||
# LANGFUSE_NEXTAUTH_URL=http://localhost:3000
|
||||
# LANGFUSE_TELEMETRY_ENABLED=false
|
||||
#
|
||||
# 可选:自动化首次启动(填写后直接注入管理员+项目,跳过 UI 注册)
|
||||
# LANGFUSE_INIT_ORG_NAME=WeKnora
|
||||
# LANGFUSE_INIT_PROJECT_NAME=WeKnora
|
||||
# LANGFUSE_INIT_PROJECT_PUBLIC_KEY=pk-lf-weknora-init
|
||||
# LANGFUSE_INIT_PROJECT_SECRET_KEY=sk-lf-weknora-init
|
||||
# LANGFUSE_INIT_USER_EMAIL=admin@example.com
|
||||
# LANGFUSE_INIT_USER_NAME=Admin
|
||||
# LANGFUSE_INIT_USER_PASSWORD=change-me-please
|
||||
|
||||
# 时区设置,默认为 Asia/Shanghai
|
||||
# 影响系统时间显示和日志时间戳
|
||||
# 常用值:Asia/Shanghai, Asia/Tokyo, America/New_York, Europe/London, UTC
|
||||
|
||||
Reference in New Issue
Block a user