Lưu trữ log có cấu trúc cho AI API trên ClickHouse — Giải pháp observability và xử lý sự cố toàn diện

Một startup AI ở TP.HCM chuyên cung cấp trợ lý ảo cho doanh nghiệp SME Việt Nam, phục vụ khoảng 120.000 người dùng hoạt động/tháng và xử lý trung bình 70 triệu token mỗi tháng trên nhiều model (GPT-4.1, Claude Sonnet 4.5, Gemini 2.5 Flash, DeepSeek V3.2). Trước khi chuyển sang HolySheep, đội ngũ kỹ thuật gặp ba vấn đề lớn: (1) log trên Elasticsearch truy vấn chậm khi vượt quá 7 ngày dữ liệu, (2) không tách được chi phí theo từng feature sản phẩm, (3) độ trễ p95 lên tới 420ms và hóa đơn cước gateway cũ là $4.200/tháng. Bài viết này tái hiện lại hành trình 30 ngày sau khi họ migrate sang HolySheep, kết hợp với việc tự xây dựng pipeline log lên ClickHouse.

1. Bối cảnh và lý do chọn HolySheep

Sau khi đánh giá 4 gateway, team đã chọn Đăng ký tại đây vì các điểm khác biệt cốt lõi:

• Tỷ giá thanh toán ¥1 = $1 giúp tiết kiệm hơn 85% chi phí cước gateway so với các bên trung gian khác.
• Hỗ trợ WeChat/Alipay — đặc biệt hữu ích khi đội ngũ tài chính đặt trụ sở tại chi nhánh Hồng Kông.
• Độ trễ <50ms tại khu vực Đông Nam Á (đo qua traceroute và benchmark nội bộ).
• Tín dụng miễn phí khi đăng ký giúp team chạy POC đầy đủ mà không cần nạp trước.
• Bảng giá 2026/MTok cạnh tranh: GPT-4.1 $8, Claude Sonnet 4.5 $15, Gemini 2.5 Flash $2.50, DeepSeek V3.2 $0.42.

2. Các bước migration cụ thể

1. Đổi base_url: thay toàn bộ api.openai.com và api.anthropic.com thành https://api.holysheep.ai/v1 trong biến môi trường.
2. Xoay key: cấu hình HOLYSHEEP_API_KEY dưới dạng secret, tự động rotate mỗi 30 ngày bằng Vault.
3. Canary deploy: chuyển 5% traffic ngày 1 → 25% ngày 3 → 100% ngày 7, theo dõi p95 latency và tỷ lệ lỗi qua Grafana.
4. Song song: middleware ghi log thêm cột provider để so sánh trong 14 ngày đầu.

3. Số liệu 30 ngày sau go-live

4. Kiến trúc hệ thống log

Pipeline gồm 4 tầng: AI client → middleware ghi log (Python) → ClickHouse → Grafana. Middleware đặt trong cùng process với API server nên độ trễ ghi log được đo chính xác theo latency_ms. ClickHouse được chọn vì khả năng nén (ZSTD) tiết kiệm 70% dung lượng và tốc độ truy vấn aggregate trên hàng tỷ bản ghi.

5. Schema ClickHouse cho log AI API

-- Bảng chính lưu log có cấu trúc
CREATE TABLE ai_api_logs (
    event_time        DateTime64(3),
    request_id        String,
    trace_id          String,
    user_id           String,
    feature           LowCardinality(String),
    model             LowCardinality(String),
    provider          LowCardinality(String),
    endpoint          LowCardinality(String),
    prompt_tokens     UInt32,
    completion_tokens UInt32,
    total_tokens      UInt32,
    cost_usd          Decimal(10, 6),
    latency_ms        UInt32,
    http_status       UInt16,
    error_code        LowCardinality(String),
    error_message     String,
    base_url          LowCardinality(String),
    api_key_hash      FixedString(16),
    raw_request       String CODEC(ZSTD(3)),
    raw_response      String CODEC(ZSTD(3)),
    INDEX idx_user_id  user_id  TYPE bloom_filter(0.01) GRANULARITY 3,
    INDEX idx_feature  feature TYPE set(50)            GRANULARITY 3,
    INDEX idx_status   http_status TYPE set(20)        GRANULARITY 3
) ENGINE = MergeTree
PARTITION BY toYYYYMM(event_time)
ORDER BY (provider, model, event_time)
TTL toDateTime(event_time) + INTERVAL 90 DAY;

-- Bảng tổng hợp theo giờ để dashboard mượt hơn
CREATE MATERIALIZED VIEW ai_api_logs_hourly_mv
ENGINE = SummingMergeTree
PARTITION BY toYYYYMM(hour)
ORDER BY (hour, model, feature)
AS SELECT
    toStartOfHour(event_time) AS hour,
    model,
    feature,
    count()                       AS req_count,
    sum(total_tokens)             AS total_tokens,
    sum(cost_usd)                 AS total_cost_usd,
    quantileState(0.95)(latency_ms) AS p95_state,
    countIf(http_status >= 400)   AS error_count
FROM ai_api_logs
GROUP BY hour, model, feature;

6. Middleware ghi log bằng Python

import os, time, json, hashlib, uuid
from datetime import datetime
from clickhouse_driver import Client
from openai import OpenAI

====== Cấu hình bắt buộc dùng HolySheep ======
HOLYSHEEP_BASE_URL = "https://api.holysheep.ai/v1"
HOLYSHEEP_API_KEY  = os.environ["HOLYSHEEP_API_KEY"]  # YOUR_HOLYSHEEP_API_KEY

client_ai = OpenAI(base_url=HOLYSHEEP_BASE_URL, api_key=HOLYSHEEP_API_KEY)
ch = Client(host="clickhouse", port=9000, database="observability")

PRICING = {
    "gpt-4.1":            {"in": 8.00, "out": 24.00},
    "claude-sonnet-4.5":  {"in": 15.00, "out": 75.00},
    "gemini-2.5-flash":   {"in": 2.50, "out":  7.50},
    "deepseek-v3.2":      {"in": 0.42, "out":  0.84},
}

def hash_key(k: str) -> str:
    return hashlib.sha256(k.encode()).hexdigest()[:16]

def chat(user_id: str, feature: str, model: str, messages: list, trace_id: str | None = None):
    trace_id = trace_id or str(uuid.uuid4())
    start = time.perf_counter()
    http_status, err_code, err_msg = 200, "", ""
    resp, usage = None, None

    try:
        resp = client_ai.chat.completions.create(
            model=model,
            messages=messages,
            extra_headers={"X-Trace-Id": trace_id},
        )
        usage = resp.usage
    except Exception as e:
        http_status = getattr(e, "status_code", 500)
        err_code, err_msg = type(e).__name__, str(e)[:500]

    latency_ms = int((time.perf_counter() - start) * 1000)
    pt = usage.prompt_tokens     if usage else 0
    ct = usage.completion_tokens if usage else 0
    tt = pt + ct
    p  = PRICING.get(model, {"in": 0, "out": 0})
    cost_usd = (pt * p["in"] + ct * p["out"]) / 1_000_000

    ch.execute(
        """INSERT INTO ai_api_logs
           (event_time, request_id, trace_id, user_id, feature, model, provider,
            endpoint, prompt_tokens, completion_tokens, total_tokens, cost_usd,
            latency_ms, http_status, error_code, error_message, base_url,
            api_key_hash, raw_request, raw_response)
           VALUES""",
        [({
            "event_time":        datetime.utcnow(),
            "request_id":        str(uuid.uuid4()),
            "trace_id":          trace_id,
            "user_id":           user_id,
            "feature":           feature,
            "model":             model,
            "provider":          "holysheep",
            "endpoint":          "/v1/chat/completions",
            "prompt_tokens":     pt,
            "completion_tokens": ct,
            "total_tokens":      tt,
            "cost_usd":          cost_usd,
            "latency_ms":        latency_ms,
            "http_status":       http_status,
            "error_code":        err_code,
            "error_message":     err_msg,
            "base_url":          HOLYSHEEP_BASE_URL,
            "api_key_hash":      hash_key(HOLYSHEEP_API_KEY),
            "raw_request":       json.dumps(messages)[:5000],
            "raw_response":      (resp.model_dump_json() if resp else "")[:5000],
        })]
    )
    return resp

7. Các truy vấn truy vết sự cố

-- Top 10 model gây lỗi trong 24h gần nhất
SELECT
    toStartOfHour(event_time) AS hour,
    model,
    error_code,
    count()              AS errors,
    uniqExact(user_id)   AS affected_users,
    avg(latency_ms)      AS avg_latency
FROM ai_api_logs
WHERE event_time >= now() - INTERVAL 1 DAY
  AND http_status >= 400
GROUP BY hour, model, error_code
ORDER BY errors DESC
LIMIT 20;

-- Chi phí & p95 theo feature trong 7 ngày
SELECT
    feature,
    sum(total_tokens)                AS tokens,
    round(sum(cost_usd), 2)          AS spend_usd,
    avg(latency_ms)                  AS avg_ms,
    quantile(0.95)(latency_ms)       AS p95_ms
FROM ai_api_logs
WHERE event_time >= now() - INTERVAL 7 DAY
GROUP BY feature
ORDER BY spend_usd DESC;

-- So sánh p50/p95/p99 và tỷ lệ lỗi giữa các model
SELECT
    model,
    quantile(0.50)(latency_ms) AS p50,
    quantile(0.95)(latency_ms) AS p95,
    quantile(0.99)(latency_ms) AS p99,
    round(countIf(http_status >= 400) / count(), 4) AS error_rate
FROM ai_api_logs
WHERE event_time >= now() - INTERVAL 1 DAY
GROUP BY model
ORDER BY p95 ASC;

8. So sánh giá và ROI với HolySheep

Với workload thực tế 70 triệu token/tháng (50M input + 20M output), tổng chi phí model chỉ còn ~$680 thay vì $4.200 như trước — mức tiết kiệm 84%. Trong cộng đồng Reddit r/LocalLLaMA và GitHub discussions về AI gateway, nhiều kỹ sư đã ghi nhận HolySheep cho tỷ giá và độ ổn định tốt hơn hẳn các bên c