第 15 课合并到第 6 步时一句带过:「算 token 与成本」。这一课就把那一步摊开。核心是一条贯穿 Langfuse 的原则——provided 压倒 computed:
你(或 LLM 提供商)报上来的 usage / cost 一律优先采信;只有你什么都没报时,Langfuse 才亲自动手:用分词器数 token、
按价目表算钱。这正是第 3 课 provided_* 与 usage_details 两套字段的来历,也是第 8 课那些 provided_* Map 列存在的理由。
合并出 observation 后,getGenerationUsage 接手,把「模型 → token → 价格 → 成本」串成一条流水线。每一步的输入都可能来自你上报的 provided_*,
也可能由系统补算:
findModel 用正则把模型名匹配到价目 → getUsageUnits 取/算 token → matchPricingTier 选价目层 → calculateUsageCosts 算钱。产物写进 observation 的 usage_details/cost_details。源码:IngestionService/index.ts:1057-1143。domain/observations.ts 的 usageDetails/costDetails,单价结构对齐 worker/src/constants/default-model-prices.json;值为示例):先把用量拆成 input/output token,再按该 model 的各自单价折算成 costDetails 求和得 total_cost。注意 output 单价通常比 input 贵,所以「话多」比「读得多」更费钱。若命中提示缓存,input 走更低的 input_cached_tokens 阶梯价(gpt-4o 约 $1.25/1M,为普通 input 的一半)。// ① 模型匹配:拿 provided_model_name 去 models 表正则匹配 const { model, pricingTiers } = provided_model_name ? await findModel({ projectId, model: provided_model_name }) : { model: null, pricingTiers: [] }; // ② 取/算 token;③ 选价目层;④ 算成本 const usage = await getUsageUnits(observationRecord, model); const tier = matchPricingTier(pricingTiers, usage.usage_details); const cost = IngestionService.calculateUsageCosts(tier.prices, obs, usage.usage_details); return { ...usage, ...cost, internal_model_id: model?.id, /* 价目层 */ };
token 和成本各有一条「provided 还是 computed」的岔路,规则一模一样:你给了,就用你的;你没给,系统才算。但「系统才算」是有前提的。
getUsageUnits(index.ts:1145+,分词条件)与 calculateUsageCosts(「给了任一 cost 点就不再算」)。| 维度 | provided(你上报) | computed(系统补算,仅当你没给) |
|---|---|---|
| token 用量 | 原样采用 provided_usage_details | 匹配到模型 + level≠ERROR 时,用 tokenizerId 对 input/output 分词计数 |
| 成本 | 给了任一 cost 点 → 全用 provided_cost_details,不再算别的 | 对每种用量:价格 × 数量,加总为 total_cost |
| 为什么这样 | 来源更可信(LLM API 常返回精确 token 数) | 无来源时的合理估计,不能与 provided 混用 |
落到真实埋点里,这两条岔路对应两种很常见的接入方式:
你用 OpenAI / Anthropic 官方 SDK,响应体里自带 usage(精确的 prompt/completion token 数)。SDK 把它原样上报,Langfuse 照单全收——既准确又省去分词开销。这是最理想的情况。
你直接拼 HTTP 调一个模型、或用了不返回 usage 的网关,埋点里没有 token 数。只要模型名能匹配上、且不是 ERROR,Langfuse 就替你分词数 token、按价目算钱,让你照样有用量和成本可看。
举个具体的数:一次 gpt-4o 调用,computed 路径数出 input 1,000 token、output 500 token;价目表里这个模型 input 单价 $2.5/百万、output $10/百万,
于是 cost_details = { input: 0.0025, output: 0.005, total: 0.0075 }。如果你的 SDK 本就报了 usage = {input:1000, output:500},
第②步就跳过分词、直接用这两个数;如果你连 cost 也报了,第④步连乘法都省了,整条成本直接采信你的。能少算就少算,能信你就信你。
第③步 matchPricingTier 是较新的精细化能力:一个模型可以有多个价目层,每层带一组条件——把 usage 里匹配某模式的用量求和、
和阈值比较(>、>=、< 等,多条件 AND)。于是「超过 128k token 走长上下文高价」「缓存 token 走折扣价」这类按量分层定价就能精确表达。
选中的层提供每种用量类型的单价,第④步再据此算钱。没有命中任何层,就退回模型的基础价格——分层只是在「一价到底」之上多了一层灵活度。
computed 这条路的起点,是把你上报的模型名字符串(如 gpt-4o-2024-08-06)对应到一条价目记录。这事由 findModel 在
Postgres 的 models 表上完成,靠的是一句正则匹配:
match_pattern;用 Postgres 的 ~ 运算符拿你的模型名去套。正则允许大小写不敏感、可选的提供商前缀等灵活写法。WHERE project_id = ? OR project_id IS NULL,再 ORDER BY project_id——你自定义的模型价格盖过内置的,方便覆盖默认定价或加自有模型。ORDER BY start_date DESC + LIMIT 1:价格会随时间调整,匹配时取生效日期最近的那一条,于是历史数据按当时价、新数据按新价。匹配上的 model 记录里,除了价格,还有一个关键字段 tokenizer_id——它决定了 computed 时用哪种分词器数 token(不同模型家族分词规则不同)。
分词本身在 worker/src/features/tokenisation 里,甚至放进独立 worker 线程跑(tokenCountAsync),免得大文本分词阻塞主流程;失败再退回同步 tokenCount。
这又是第 8 课 provided_* 与计算列分离的写入侧来源:provided 进 provided_usage_details,算出来的进 usage_details,互不污染。
看一条真实的内置规则(Langfuse 自带约 150+ 个模型价格):gpt-4o 的 match_pattern 是 (?i)^(openai/)?(gpt-4o)$——
大小写不敏感、可带可不带 openai/ 前缀,精确匹配 gpt-4o。而带日期的版本(如 gpt-4o-2024-05-13)有各自独立的价格行,
因为不同发布日的定价可能不同。这套「正则 + 内置价目表」让 Langfuse 开箱即认得主流模型,你也能在 models 表里加自己的行覆盖或扩展——
正则给了灵活度,project_id 优先级给了覆盖权,start_date 给了时间维度。三者合起来,就是一套能跟着模型市场演进的活的定价系统。
getGenerationUsage 四步:findModel(匹配模型/价格)→ getUsageUnits(取/算 token)→ matchPricingTier(选价目层)→ calculateUsageCosts(算钱)。tokenizerId 对 input/output 分词计数。findModel:Postgres ~ match_pattern 正则匹配;项目模型盖过全局,start_date 最新者胜——历史按旧价、新数据按新价。worker/src/features/tokenisation,可走独立线程(tokenCountAsync);结果分别落第 8 课的 provided_* 与 usage_details 列,互不污染。
At step 6 of Lesson 15's merge we said in passing: "compute tokens & cost". This lesson unfolds that step. The core is a principle running through all
of Langfuse — provided beats computed: the usage / cost you (or the LLM provider) report are always trusted first; only
when you report nothing does Langfuse roll up its sleeves: count tokens with a tokenizer, price it from a rate
card. This is the origin of Lesson 3's two field sets provided_* and usage_details, and the reason Lesson 8's
provided_* Map columns exist.
Once the observation is merged, getGenerationUsage takes over, threading "model → tokens → price → cost" into one pipeline. Each step's
input may come from your reported provided_*, or be backfilled by the system:
findModel regex-matches the model name to a price → getUsageUnits takes/counts tokens → matchPricingTier picks the tier → calculateUsageCosts computes the cost. The outputs land in the observation's usage_details/cost_details. Source: IngestionService/index.ts:1057-1143.usageDetails/costDetails in domain/observations.ts, price structure per worker/src/constants/default-model-prices.json; values illustrative): usage splits into input/output tokens, each converted at the model's own unit price into costDetails and summed into total_cost. Output is usually pricier than input, so “talking a lot” costs more than “reading a lot”. On a prompt-cache hit, input is charged at the lower input_cached_tokens tier (e.g. gpt-4o ≈ $1.25/1M, half of normal input).// ① model match: regex-match provided_model_name against the models table const { model, pricingTiers } = provided_model_name ? await findModel({ projectId, model: provided_model_name }) : { model: null, pricingTiers: [] }; // ② take/count tokens; ③ pick tier; ④ compute cost const usage = await getUsageUnits(observationRecord, model); const tier = matchPricingTier(pricingTiers, usage.usage_details); const cost = IngestionService.calculateUsageCosts(tier.prices, obs, usage.usage_details); return { ...usage, ...cost, internal_model_id: model?.id, /* tier */ };
Tokens and cost each have a "provided or computed" fork, with identical rules: if you gave it, use yours; only if you didn't does the system compute. But "the system computes" has preconditions.
getUsageUnits (index.ts:1145+, tokenization condition) and calculateUsageCosts ("any provided cost point disables computation").| dimension | provided (you reported) | computed (system, only if you didn't) |
|---|---|---|
| token usage | take provided_usage_details as-is | if model matched + level≠ERROR, tokenize-count input/output via tokenizerId |
| cost | any cost point given → use provided_cost_details wholesale, compute nothing else | per usage type: price × units, summed to total_cost |
| why | more trustworthy source (LLM APIs often return exact token counts) | a reasonable estimate absent a source; never mixed with provided |
In real instrumentation, the two forks map to two very common integration styles:
You use the official OpenAI / Anthropic SDK; the response body carries usage (exact prompt/completion token counts). The SDK reports it as-is and Langfuse takes it whole — accurate, and no tokenization cost. The ideal case.
You hit a model over raw HTTP, or via a gateway that doesn't return usage, so there's no token count. As long as the model name matches and it isn't ERROR, Langfuse tokenizes and prices it for you, so you still get usage and cost.
A concrete number: a gpt-4o call, the computed path counts input 1,000 tokens, output 500; the rate card prices this model at $2.5/1M input,
$10/1M output, giving cost_details = { input: 0.0025, output: 0.005, total: 0.0075 }. If your SDK already reported
usage = {input:1000, output:500}, step ② skips tokenization and uses those directly; if you also reported cost, step ④ skips
even the multiplication and trusts your cost entirely. Compute as little as possible, trust you whenever possible.
Step ③ matchPricingTier is a newer fine-grained capability: a model can have several pricing tiers, each with a set of
conditions — sum the usage matching some pattern and compare to a threshold (>, >=, <…, multiple
conditions AND-ed). So "over 128k tokens → long-context higher price" or "cached tokens → discounted price" — usage-volume tiered pricing —
can be expressed precisely. The matched tier provides per-usage-type unit prices for step ④. Match no tier, and it falls back to the model's base price —
tiers just add flexibility on top of "one flat price".
The computed path begins by mapping your reported model-name string (e.g. gpt-4o-2024-08-06) to a price
record. findModel does this on Postgres's models table, via a single regex match:
match_pattern; Postgres's ~ operator tests your model name against it. The regex allows case-insensitivity, an optional provider prefix, and other flexible forms.WHERE project_id = ? OR project_id IS NULL, then ORDER BY project_id — your custom model prices override the built-in ones, handy for overriding default pricing or adding your own models.ORDER BY start_date DESC + LIMIT 1: prices change over time, so matching takes the one with the most recent effective date — historical data priced at its time, new data at the new price.Beyond price, a matched model row has a key field tokenizer_id — it decides which tokenizer counts tokens when computing
(different model families tokenize differently). Tokenization itself lives in worker/src/features/tokenisation, even running in a
separate worker thread (tokenCountAsync) so large-text tokenization doesn't block the main flow; on failure it falls back to
synchronous tokenCount. This too is the write-side origin of Lesson 8's split between provided_* and computed columns: provided
goes into provided_usage_details, the computed into usage_details, never polluting each other.
Look at one real built-in rule (Langfuse ships ~150+ model prices): gpt-4o's match_pattern is
(?i)^(openai/)?(gpt-4o)$ — case-insensitive, with or without the openai/ prefix, matching gpt-4o exactly. Dated
versions (like gpt-4o-2024-05-13) have their own separate price rows, since pricing can differ by release date. This "regex +
built-in rate card" lets Langfuse recognize mainstream models out of the box, and you can add your own rows in models to override or extend —
the regex gives flexibility, project_id precedence gives override rights, start_date gives a time dimension. Together they make a
living pricing system that evolves with the model market.
getGenerationUsage in four steps: findModel (match model/price) → getUsageUnits (take/count tokens) → matchPricingTier (pick tier) → calculateUsageCosts (compute cost).tokenizerId.findModel: Postgres ~ match_pattern regex; project models override global, latest start_date wins — history at old price, new data at new.worker/src/features/tokenisation, optionally on a separate thread (tokenCountAsync); results land in Lesson 8's provided_* vs usage_details columns, never polluting each other.