CMDC.TokenUsage (cmdc v0.5.0)

Copy Markdown View Source

公开的 token 用量 struct。

CMDC 在 Provider 层把不同 LLM 厂商的 raw usage（OpenAI 风格 prompt_tokens / completion_tokens，Anthropic 风格 input_tokens / output_tokens， Google 风格 prompt_token_count / candidates_token_count）统一归一化为本 struct。

事件协议：

  • {:agent_end, messages, %CMDC.TokenUsage{}} — 第三参数是 struct
  • CMDC.status/1 返回 :token_usage 字段为 struct，原 :total_tokens Int 字段保留

字段约定（OpenAI 行业事实标准）

  • :prompt_tokens — 输入 token 总数（Anthropic 的 input_tokens 也归到这里）
  • :completion_tokens — 输出 token 总数（Anthropic 的 output_tokens 也归到这里）
  • :total_tokens — 累计 token 总数（多数 Provider 自带；缺失时由 prompt + completion 补齐）
  • :cost_usd — 累计美元成本（基于 token 用量与模型定价计算；Provider 未配置定价时为 nil）
  • :cached_tokens — Anthropic prompt cache 命中的 token 数（Provider 不支持时为 nil）

使用

iex> CMDC.TokenUsage.new(prompt_tokens: 100, completion_tokens: 50)
%CMDC.TokenUsage{
  prompt_tokens: 100,
  completion_tokens: 50,
  total_tokens: 150,
  cost_usd: nil,
  cached_tokens: nil
}

# 从 Anthropic raw usage 归一化（total_tokens 缺失自动补齐）
iex> u = CMDC.TokenUsage.from_raw(%{input_tokens: 80, output_tokens: 40})
iex> {u.prompt_tokens, u.completion_tokens, u.total_tokens}
{80, 40, 120}

Summary

Types

t()

Functions

add(a, b)

累加另一份 token usage（用于多轮 / 多 Provider 调用聚合）。

from_raw(already)

从任意 Provider raw usage map 构造（Anthropic / OpenAI / Google 兼容）。

from_state_token_map(token_map, cost_usd \\ nil, cached_tokens \\ nil)

把 Agent State 内部 token map + cost_usd 转换为公开 struct。

new(fields \\ [])

从 keyword / map 构造 TokenUsage struct。

Types

t()

@type t() :: %CMDC.TokenUsage{
  cached_tokens: non_neg_integer() | nil,
  completion_tokens: non_neg_integer(),
  cost_usd: float() | nil,
  prompt_tokens: non_neg_integer(),
  total_tokens: non_neg_integer()
}

Functions

add(a, b)

@spec add(t(), t()) :: t()

累加另一份 token usage（用于多轮 / 多 Provider 调用聚合）。

  • prompt_tokens / completion_tokens / total_tokens / cached_tokens 取加和 （nil 视为 0）
  • cost_usd 也取加和（双方都是数字时累加；任意一方为 nil 时取另一方的值）

示例

iex> a = CMDC.TokenUsage.new(prompt_tokens: 10, completion_tokens: 5)
iex> b = CMDC.TokenUsage.new(prompt_tokens: 20, completion_tokens: 10)
iex> CMDC.TokenUsage.add(a, b)
%CMDC.TokenUsage{prompt_tokens: 30, completion_tokens: 15, total_tokens: 45,
                 cost_usd: nil, cached_tokens: nil}

from_raw(already)

@spec from_raw(map() | t()) :: t()

从任意 Provider raw usage map 构造（Anthropic / OpenAI / Google 兼容）。

字段映射：

  • prompt_tokens ← :prompt_tokens / :input_tokens / :prompt_token_count
  • completion_tokens ← :completion_tokens / :output_tokens / :candidates_token_count
  • total_tokens ← :total_tokens（缺失时由 prompt + completion 补齐）
  • cached_tokens ← :cache_read_input_tokens / :cached_tokens

支持 atom 或 string key 的混合输入。

from_state_token_map(token_map, cost_usd \\ nil, cached_tokens \\ nil)

@spec from_state_token_map(map(), float() | nil, non_neg_integer() | nil) :: t()

把 Agent State 内部 token map + cost_usd 转换为公开 struct。

Agent 内部为兼容性保留扩展 map（含 :context_window / :current_context_tokens, 这两个字段是上下文窗口元数据，不属于"用量"，不进入公开 struct）。

new(fields \\ [])

@spec new(map() | keyword()) :: t()

从 keyword / map 构造 TokenUsage struct。

缺省字段：prompt_tokens / completion_tokens / total_tokens 默认 0, cost_usd / cached_tokens 默认 nil。

示例

iex> CMDC.TokenUsage.new()
%CMDC.TokenUsage{prompt_tokens: 0, completion_tokens: 0, total_tokens: 0,
                 cost_usd: nil, cached_tokens: nil}

iex> CMDC.TokenUsage.new(prompt_tokens: 10, completion_tokens: 5, cost_usd: 0.0001)
%CMDC.TokenUsage{prompt_tokens: 10, completion_tokens: 5, total_tokens: 15,
                 cost_usd: 0.0001, cached_tokens: nil}