使用文档

AI Tracker SDK

AntDock AI Tracker 专为 LLM 调用追踪设计，帮助您监控和分析 AI 应用的使用情况和成本。

特点

  • 元数据优先: 默认只追踪调用元数据，不记录 prompt 和 response 内容；请勿在自定义标签中传入敏感信息
  • 费用来源可追溯: 区分提供方上报、内置单价估算和无法计算；估算金额不等同账单
  • 性能指标: 延迟、TTFT、tokens/秒 等关键指标
  • 多模型支持: OpenAI、Anthropic、DeepSeek 等主流模型

安装

控制台的「AI 调用 → 接入指南」为 Node SDK、浏览器 SDK 和 HTTP API 分别提供「复制给 AI 的接入说明」。说明随当前应用及采集域名生成，要求复用实际模型调用，不发送示例请求或编造 Token、费用；不包含模型 API Key。AI 完成代码修改后，需确认一条真实调用在控制台可查询。

Script 标签

<script defer src="https://your-domain.com/static/antdock-ai.js"
  data-app-id="your-app-id"
  data-endpoint="https://your-domain.com">
</script>

npm

npm install https://antdock.com/static/sdk/antdock-ai-tracker-0.1.0.tgz

import { AntDockAI } from '@antdock/ai-tracker'

const tracker = new AntDockAI({
  appId: 'your-app-id',
  endpoint: 'https://your-domain.com'
})

快速开始

手动追踪

import { AntDockAI } from '@antdock/ai-tracker'

const tracker = new AntDockAI({
  appId: 'your-app-id',
  endpoint: 'https://your-domain.com'
})

// 开始计时
const timer = tracker.startTimer()

// 调用 LLM
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }]
})

// 追踪调用
tracker.trace({
  provider: 'openai',
  model: 'gpt-4o',
  promptTokens: response.usage.prompt_tokens,
  completionTokens: response.usage.completion_tokens,
  latencyMs: timer.elapsed(),
  status: 'success'
})

OpenAI 自动追踪

import OpenAI from 'openai'
import { AntDockAI } from '@antdock/ai-tracker'

const openai = new OpenAI()
const tracker = new AntDockAI({
  appId: 'your-app-id',
  endpoint: 'https://your-domain.com'
})

// 包装 OpenAI 客户端
const wrappedOpenAI = tracker.wrapOpenAI(openai)

// 正常使用，自动追踪
const response = await wrappedOpenAI.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello' }]
})

API 参考

trace(data)

追踪 LLM 调用。

tracker.trace({
  // 必填字段
  provider: 'openai',           // 提供商: openai, anthropic, deepseek, etc.
  model: 'gpt-4o',              // 模型名称

  // Token 使用
  promptTokens: 150,            // 输入 token 数
  completionTokens: 50,         // 输出 token 数
  costUsd: 0.0005,              // 可选：提供方上报的实际金额（含 0）

  // 性能指标
  latencyMs: 1500,              // 总延迟 (毫秒)
  timeToFirstTokenMs: 200,      // 首个 token 时间 (毫秒)

  // 参数配置
  temperature: 0.7,
  topP: 1.0,
  maxTokens: 1000,
  frequencyPenalty: 0,
  presencePenalty: 0,

  // 状态
  status: 'success',            // success, error
  errorType: '',                // timeout, rate_limit, invalid_request, etc.
  errorCode: '',
  finishReason: 'stop',         // stop, length, content_filter

  // 元数据
  promptTemplate: 'chat',       // 模板名称
  feature: 'customer_support',  // 功能标签
  userId: 'user_123',           // 用户 ID

  // 流式响应
  streaming: false,
  streamChunks: null
})

startTimer()

创建计时器用于测量延迟。

const timer = tracker.startTimer()

// 执行操作...

const elapsedMs = timer.elapsed()
console.log(`耗时: ${elapsedMs}ms`)

wrapOpenAI(client)

包装 OpenAI 客户端实现自动追踪。

const openai = new OpenAI()
const wrappedOpenAI = tracker.wrapOpenAI(openai)

// 自动追踪所有调用
const response = await wrappedOpenAI.chat.completions.create({...})

flush()

立即发送队列中的数据。

await tracker.flush()

费用口径

优先传入提供方实际返回的 costUsd（包括免费调用的 0）。未传入时，SDK 仅对内置价目表中可识别的模型按输入/输出 Token 估算；未知模型标记为“无法计算”，不会套用默认价格。页面会分别显示上报、估算、旧版未标注来源和无法计算的请求数。

直接调用 /api/ai/trace 时，如传入提供方金额，请同时传 "costSource":"reported"，才能区分明确的零费用与未提供费用。

内置单价可能落后于提供方调整，且不包含缓存 Token、阶梯价、折扣、渠道加价或汇率。请以提供方账单为准；需要对账时，在服务端上报实际金额。浏览器不应持有提供方密钥。

框架集成

LangChain

import { ChatOpenAI } from '@langchain/openai'
import { AntDockAI } from '@antdock/ai-tracker'

const tracker = new AntDockAI({...})

const model = new ChatOpenAI({
  modelName: 'gpt-4o',
  callbacks: [{
    handleLLMEnd(output) {
      const usage = output.llmOutput?.tokenUsage
      tracker.trace({
        provider: 'openai',
        model: 'gpt-4o',
        promptTokens: usage?.promptTokens,
        completionTokens: usage?.completionTokens,
        status: 'success'
      })
    },
    handleLLMError(error) {
      tracker.trace({
        provider: 'openai',
        model: 'gpt-4o',
        status: 'error',
        errorType: 'api_error'
      })
    }
  }]
})

Vercel AI SDK

import { openai } from '@ai-sdk/openai'
import { generateText } from 'ai'
import { AntDockAI } from '@antdock/ai-tracker'

const tracker = new AntDockAI({...})

const timer = tracker.startTimer()

const { text, usage } = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Hello'
})

tracker.trace({
  provider: 'openai',
  model: 'gpt-4o',
  promptTokens: usage.promptTokens,
  completionTokens: usage.completionTokens,
  latencyMs: timer.elapsed(),
  status: 'success'
})

Node.js 服务端

import { AntDockAI } from '@antdock/ai-tracker'
import OpenAI from 'openai'

const tracker = new AntDockAI({
  appId: 'your-app-id',
  endpoint: 'https://your-domain.com'
})

const openai = new OpenAI()

export async function chat(messages, userId) {
  const timer = tracker.startTimer()

  try {
    const response = await openai.chat.completions.create({
      model: 'gpt-4o',
      messages
    })

    tracker.trace({
      provider: 'openai',
      model: 'gpt-4o',
      promptTokens: response.usage.prompt_tokens,
      completionTokens: response.usage.completion_tokens,
      latencyMs: timer.elapsed(),
      status: 'success',
      finishReason: response.choices[0].finish_reason,
      userId
    })

    return response.choices[0].message.content
  } catch (error) {
    tracker.trace({
      provider: 'openai',
      model: 'gpt-4o',
      latencyMs: timer.elapsed(),
      status: 'error',
      errorType: error.code || 'unknown',
      errorCode: error.status,
      userId
    })
    throw error
  }
}

流式响应追踪

const timer = tracker.startTimer()
let ttft = null
let chunks = 0
let completionTokens = 0

const stream = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [...],
  stream: true
})

for await (const chunk of stream) {
  if (ttft === null) {
    ttft = timer.elapsed()
  }
  chunks++

  // 处理 chunk...
}

tracker.trace({
  provider: 'openai',
  model: 'gpt-4o',
  latencyMs: timer.elapsed(),
  ttftMs: ttft,
  streaming: true,
  streamChunks: chunks,
  status: 'success'
})

配置选项

interface AntDockAIConfig {
  appId: string        // 必填，App ID
  endpoint?: string        // API 端点
  batchSize?: number       // 批量大小，默认 10
  flushInterval?: number   // 刷新间隔 (ms)，默认 5000
  debug?: boolean          // 调试模式
}

追踪数据结构

interface LLMTrace {
  // 基础信息
  provider: string
  model: string
  modelVersion?: string

  // Token 使用
  promptTokens?: number
  completionTokens?: number
  totalTokens?: number

  // 费用：优先填入提供方上报值；不填时可能估算或无法计算
  costUsd?: number
  costInputUsd?: number
  costOutputUsd?: number

  // 性能指标
  latencyMs?: number
  ttftMs?: number
  tokensPerSecond?: number

  // 参数
  temperature?: number
  topP?: number
  maxTokens?: number
  frequencyPenalty?: number
  presencePenalty?: number

  // 状态
  status: 'success' | 'error'
  errorType?: string
  errorCode?: string | number
  finishReason?: string

  // 流式相关
  streaming?: boolean
  streamChunks?: number

  // 元数据
  promptTemplate?: string
  feature?: string
  userId?: string

  // 时间戳 (自动填充)
  timestamp?: number
}

分析指标

追踪数据可在 AntDock 面板中查看以下指标：

  • 调用量: 按模型、提供商、时间分布
  • Token 使用: 输入/输出 token 趋势
  • 成本分析: 按模型、功能的成本明细
  • 性能指标: 平均延迟、P95、TTFT
  • 错误率: 错误类型分布、趋势
  • 用户分析: 按用户的使用量和成本

调试

const tracker = new AntDockAI({
  appId: 'your-app-id',
  endpoint: 'https://your-domain.com',
  debug: true
})

调试模式下，所有追踪数据会输出到控制台。

伙伴站点Around the web

实用工具与技术笔记，继续探索。Tools and ideas for your next project.