ailens360

ailens360

为 AILens360 反向代理写的 Go 客户端胶水层。给 eino 风格的 OpenAI ChatModel 套上 BaseURL 改写 + 每请求 telemetry header 注入。

AILens360 是什么

AILens360 是开源、自部署、低代码侵入的 AI 应用可观测平台 —— "360° observability for every LLM call"。

核心做法：在你的应用和真实上游（OpenAI / Anthropic / Gemini / DeepSeek / vLLM / Ollama / ……）之间放一个反向代理。你只需要：

1. 把 baseURL 从 https://api.openai.com/v1 改成 http(s)://<ailens360-host>/p/https://api.openai.com/v1 ——/p/ 后面直接拼完整上游 URL
2. 加一个请求头 X-AILens-Project-Key: <控制台分配的项目密钥>
3. 原本的 Authorization / x-api-key 透传给上游，AILens360 不持有、不存储真实 API Key

之后所有调用都会被记录：请求/响应原文、流式 SSE 解析、token / cost 统计、TTFT / TTFB / TPS 等延迟指标、错误归因；按 Project / User / Session / Trace 维度聚合检索。

没有 SDK 强依赖，多数 OpenAI 兼容客户端只改一行 baseURL 就接入了。

这个包做什么

直接在 Go 里改两件事会很啰嗦——拼前缀 URL、给 *http.Client.Transport 套一层 RoundTripper、再让 RoundTripper 从 req.Context() 取 user/session/trace。本包把它们封成 4 个文件：

一分钟接入

import (
    "context"

    "github.com/CoolBanHub/aggo/pkg/ailens360"
    "github.com/cloudwego/eino-ext/components/model/openai"
)

func main() {
    // 1) 配置缺一即 nil；nil 时 Apply 直接 no-op，应用照常跑、不走代理。
    dec := ailens360.NewDecorator(
        "https://ailens360.example.com/p", // 控制台给的 proxy_prefix
        "<64-char project_key>",
    )

    // 2) 像平时一样构造 OpenAI ChatModel，Apply 之后 BaseURL 被改成
    //    "<proxy>/<upstream>"，HTTPClient 自动注入 telemetry header。
    cfg := &openai.ChatModelConfig{
        APIKey:  "sk-real-upstream-key", // 透传给上游
        BaseURL: "https://api.openai.com/v1",
        Model:   "gpt-4o-mini",
    }
    dec.Apply(cfg)

    chatModel, _ := openai.NewChatModel(context.Background(), cfg)

    // 3) 调用前把 user / session / trace 塞进 ctx；
    //    同一个 chatModel 实例可服务任意调用方，不用每次重建。
    ctx := ailens360.WithTrace(context.Background(), ailens360.TraceConfig{
        ID:        "trace_xxx", // 想要稳定 trace 就自己生成（建议 SHA1(turn 关键参数)）
        Name:      "customer_agent_turn",
        UserID:    "user_alice_42",
        SessionID: "group_1:user_alice_42",
        Tag:       "prod,channel=htsy",
    })

    _, _ = chatModel.Generate(ctx, /* messages */ nil)
}

完整 demo 见 example/ailens360_test/，里面是一个用 ReAct 工具调用 + AILens360 trace 的端到端例子。

ctx header 对照表

telemetryHeaders.RoundTrip 每次出站请求都会读 req.Context()，按下表把非空值拍到 header：

WithTrace(ctx, TraceConfig{…}) 是上面 5 个的一次性聚合写法。

固定不动的 X-AILens-Project-Key 由 NewDecorator 时传入，每个请求都会自动加，和 ctx 无关。

全局 vs 局部

// 进程级单例：服务启动时设一次，业务代码不感知。
ailens360.SetGlobal(dec)

// 任意 openai.ChatModelConfig 在构造前调一下：
ailens360.ApplyGlobal(cfg) // 返回 true 表示全局 Decorator 生效

适合在大型项目里把"是否启用 AILens360"做成开关：env 没配 → SetGlobal(nil) → ApplyGlobal 全是 no-op → 应用代码零分支。

设计取舍

• per-call telemetry 走 ctx 而不是参数：保持 *openai.ChatModel 是单例、可在 goroutine 间共享；调用方只关心"这次请求是谁/什么会话"，不关心 transport 细节。
• NewDecorator 容忍空配置：proxyPrefix 或 projectKey 任一空就返回 nil，调用方不用写 if dec != nil 分支；Apply / DecorateBaseURL / HTTPClient 在 nil receiver 上都是 no-op。
• 不预设上游：DecorateBaseURL 只做字符串拼接，OpenAI / Anthropic / Gemini / DeepSeek / vLLM 都一样用。
• 真实上游 Key 不经过这个包：Authorization 由 openai.ChatModel 内部按 APIKey 字段塞，透传到上游；AILens360 也只是中转，不落库。

相关链接

• AILens360 项目：https://github.com/CoolBanHub/ailens360
• AILens360 接入说明（baseURL / project_key 协议）：见上游仓库 docs/api-design.md