Tài liệu

Bạn thấy gì trong console

Console là Langfuse OSS với overlay Vết. Langfuse ghi lần gọi model. Vết ghi cả lộ trình kênh, RAG và tool trên cùng một lượt.

Chạy trên máy bạn

scripts/up.sh gắn overlay Vết, build console, rồi docker compose up. Lần đầu mất vài phút. Chi tiết biến môi trường nằm ở trang Tự vận hành.

git clone --recurse-submodules https://github.com/Dondo0936/langben.git
cd langben
cp .env.console.example .env
bash scripts/up.sh

Marketing http://localhost:43173. Console http://localhost:3000. Tài khoản console và khóa ingest: xem .env.console.example hoặc README.

Gửi bước đi của agent

Local demo: lấy LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY từ .env.console.example hoặc README. Trỏ baseUrl về http://localhost:3000. Production: copy key trong console của bạn. Đừng gửi khóa OpenAI, Anthropic, AWS, GCP hay Azure vào Vết. Chỉ gửi trace.

@vet/sdk nằm trong packages/sdk-js của repo này. Chưa phát hành trên npm. Console nói API Langfuse, nên SDK Langfuse cũng trỏ được vào cùng baseUrl.

import Anthropic from "@anthropic-ai/sdk"
import { wrapAnthropic, observe } from "@vet/sdk"

const vet = {
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.LANGFUSE_SECRET_KEY,
  baseUrl: "http://localhost:3000",
}

const client = wrapAnthropic(new Anthropic(), vet)

await observe(
  "hoan-tien",
  () =>
    client.messages.create({
      model: "claude-sonnet-4-5",
      max_tokens: 256,
      messages,
    }),
  { ...vet, sessionId, userId, channel: "zalo_oa", tags: ["zalo"] },
)

FPT.AI Conversation

import { wrapFptGetAnswer } from "@vet/sdk"

const getAnswer = wrapFptGetAnswer(fetch, {
  publicKey: process.env.LANGFUSE_PUBLIC_KEY,
  secretKey: process.env.LANGFUSE_SECRET_KEY,
  baseUrl: "http://localhost:3000",
})

await getAnswer({
  channel: "zalo",
  sender_id: userId,
  message: "Chính sách hoàn tiền đơn DH-88421?",
})

Kênh production Việt Nam

Trên Kênh, dán webhook vào Zalo OA, FPT.AI, Lark hoặc Google Chat. Viettel ASR/TTS hiện trên cùng một cây với lượt Zalo, không phải webhook riêng.

Zalo OA bắt chữ ký X-ZEvent-Signature. Hook sai chữ ký trả 401 và không ghi lượt.

curl -X POST http://localhost:43173/hooks/zalo/oa/<projectId> \
  -H "content-type: application/json" \
  -H "X-ZEvent-Timestamp: <ts>" \
  -H "X-ZEvent-Signature: <mac>" \
  -d '{"event_name":"user_send_text","sender":{"id":"u1"},"message":{"text":"Hoàn tiền DH-88421?"}}'

Thử local không cần app Zalo, Lark hay Google: nút Gửi thử trên trang Kênh (inbound), hoặc node scripts/zalo-fixture.mjs, zalo-bot-fixture.mjs, lark-fixture.mjs, gchat-fixture.mjs. Tin nhắn Zalo thật cần Cloudflare Tunnel tới :43173. Hướng dẫn: trang Tự vận hành, mục Cloudflare Tunnel. Teams không có webhook tin nhắn như Zalo.

OTLP

Gửi OTLP vào console (:3000). Marketing :43173 cũng nhận POST /otlp/v1/traces khi LANGFUSE_* được set, rồi ghi tiếp vào console.