feat: 采集 LLM token 用量并上报 lpt-be
- 客户端解析上游 usage(含 DeepSeek 缓存命中/未命中),跨重试累加 - 新增计价表(三档单价 + 峰谷时段),费用在结算时冻结 - 新增用量上报与本地 outbox 重试;4xx 判定为确定性拒绝,不无限重试 - 面板补充 Token/费用/调用次数与计价快照 - 顺带修复面板内联脚本转义错误(模板字面量吃掉 \n 与 \',面板一直空白)
This commit is contained in:
@@ -23,6 +23,18 @@ function mockFetchOnce() {
|
||||
return fetchMock;
|
||||
}
|
||||
|
||||
function mockFetchJson(payload: unknown, ok = true, status = 200) {
|
||||
const fetchMock = vi.fn().mockResolvedValue({
|
||||
ok,
|
||||
status,
|
||||
json: async () => payload,
|
||||
text: async () => JSON.stringify(payload),
|
||||
headers: new Headers(),
|
||||
} as unknown as Response);
|
||||
vi.stubGlobal("fetch", fetchMock);
|
||||
return fetchMock;
|
||||
}
|
||||
|
||||
function bodyOf(fetchMock: ReturnType<typeof mockFetchOnce>): Record<string, unknown> {
|
||||
const init = fetchMock.mock.calls[0][1] as RequestInit;
|
||||
return JSON.parse(String(init.body)) as Record<string, unknown>;
|
||||
@@ -64,3 +76,65 @@ describe("chat 请求体", () => {
|
||||
expect(bodyOf(fetchMock)).not.toHaveProperty("reasoning_effort");
|
||||
});
|
||||
});
|
||||
|
||||
describe("chat 返回值", () => {
|
||||
it("带回上游上报的 token 用量与模型名", async () => {
|
||||
mockFetchJson({
|
||||
model: "deepseek-flash-0715",
|
||||
choices: [{ message: { content: "ok" }, finish_reason: "stop" }],
|
||||
usage: {
|
||||
prompt_tokens: 1000,
|
||||
completion_tokens: 200,
|
||||
total_tokens: 1200,
|
||||
prompt_cache_hit_tokens: 800,
|
||||
prompt_cache_miss_tokens: 200,
|
||||
},
|
||||
});
|
||||
|
||||
const result = await chat(llmConfig, [{ role: "user", content: "hi" }]);
|
||||
|
||||
expect(result.content).toBe("ok");
|
||||
expect(result.model).toBe("deepseek-flash-0715");
|
||||
expect(result.finishReason).toBe("stop");
|
||||
expect(result.usageSource).toBe("upstream");
|
||||
expect(result.usage).toMatchObject({
|
||||
promptTokens: 1000,
|
||||
completionTokens: 200,
|
||||
cacheHitTokens: 800,
|
||||
cacheMissTokens: 200,
|
||||
});
|
||||
});
|
||||
|
||||
it("上游没带 usage 时标为 missing,字段全为 null", async () => {
|
||||
mockFetchJson({ choices: [{ message: { content: "ok" } }] });
|
||||
|
||||
const result = await chat(llmConfig, [{ role: "user", content: "hi" }]);
|
||||
|
||||
expect(result.usageSource).toBe("missing");
|
||||
expect(result.usage.promptTokens).toBeNull();
|
||||
});
|
||||
|
||||
it("返回 200 但内容为空时,把已产生的用量挂在错误上带回来", async () => {
|
||||
mockFetchJson({
|
||||
choices: [{ message: { content: "" } }],
|
||||
usage: { prompt_tokens: 500, completion_tokens: 0, total_tokens: 500 },
|
||||
});
|
||||
|
||||
await expect(chat(llmConfig, [{ role: "user", content: "hi" }])).rejects.toMatchObject({
|
||||
statusCode: 502,
|
||||
usage: { promptTokens: 500 },
|
||||
});
|
||||
});
|
||||
|
||||
it("上游报错时错误不带用量(上游没产生可计费的输出)", async () => {
|
||||
mockFetchJson({ error: "rate limited" }, false, 429);
|
||||
|
||||
await expect(chat(llmConfig, [{ role: "user", content: "hi" }])).rejects.toMatchObject({
|
||||
statusCode: 429,
|
||||
});
|
||||
await expect(chat(llmConfig, [{ role: "user", content: "hi" }])).rejects.toHaveProperty(
|
||||
"usage",
|
||||
undefined,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
+38
-5
@@ -8,12 +8,28 @@
|
||||
*/
|
||||
|
||||
import type { ReasoningEffort } from "./thinking.js";
|
||||
import { normalizeUsage, type TokenUsage, type UsageSource } from "./usage.js";
|
||||
|
||||
export interface ChatMessage {
|
||||
role: "system" | "user" | "assistant";
|
||||
content: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* 一次成功调用的返回值。
|
||||
*
|
||||
* 除了正文,还带回上游上报的 token 用量:调用方必须把它记下来,
|
||||
* 否则重试与失败尝试产生的消耗就再也拿不到了(上游不会补发)。
|
||||
*/
|
||||
export interface ChatResult {
|
||||
content: string;
|
||||
usage: TokenUsage;
|
||||
usageSource: UsageSource;
|
||||
/** 上游回显的模型名,可能与本项目配置的模型名不同 */
|
||||
model: string;
|
||||
finishReason: string | null;
|
||||
}
|
||||
|
||||
/** 单次调用的采样参数:温度与输出上限按任务类型定,思考强度按 prompt 长度定 */
|
||||
export interface ChatOptions {
|
||||
temperature?: number;
|
||||
@@ -53,6 +69,13 @@ export class LlmError extends Error {
|
||||
* 而不是用自己的指数退避——服务商限流时自己的退避往往偏短。
|
||||
*/
|
||||
public readonly retryAfterMs?: number,
|
||||
/**
|
||||
* 这次失败的调用是否已经产生了 token 消耗。
|
||||
*
|
||||
* 典型场景是上游返回 200 但内容为空:请求已经计费,只是没法用。
|
||||
* 有值时调用方必须把它计入用量,否则这部分消耗会凭空消失。
|
||||
*/
|
||||
public readonly usage?: TokenUsage,
|
||||
) {
|
||||
super(message);
|
||||
this.name = "LlmError";
|
||||
@@ -81,13 +104,13 @@ export function parseRetryAfter(value: string | null, now: number = Date.now()):
|
||||
}
|
||||
|
||||
/**
|
||||
* 非流式调用,返回完整文本
|
||||
* 非流式调用,返回正文与上游上报的 token 用量。
|
||||
*/
|
||||
export async function chat(
|
||||
config: LlmConfig,
|
||||
messages: ChatMessage[],
|
||||
options?: ChatOptions,
|
||||
): Promise<string> {
|
||||
): Promise<ChatResult> {
|
||||
if (!isAvailable(config)) {
|
||||
throw new LlmError("LLM API Key 未配置", 503);
|
||||
}
|
||||
@@ -126,13 +149,23 @@ export async function chat(
|
||||
}
|
||||
|
||||
const data = (await response.json()) as {
|
||||
choices?: { message?: { content?: string } }[];
|
||||
model?: string;
|
||||
choices?: { message?: { content?: string }; finish_reason?: string }[];
|
||||
usage?: unknown;
|
||||
};
|
||||
// 先把用量取出来:即使下面因为内容为空而抛错,这次请求也已经计费了
|
||||
const snapshot = normalizeUsage(data.usage);
|
||||
const content = data.choices?.[0]?.message?.content;
|
||||
if (!content) {
|
||||
throw new LlmError("LLM 返回内容为空", 502);
|
||||
throw new LlmError("LLM 返回内容为空", 502, undefined, snapshot.usage);
|
||||
}
|
||||
return content;
|
||||
return {
|
||||
content,
|
||||
usage: snapshot.usage,
|
||||
usageSource: snapshot.source,
|
||||
model: data.model ?? config.model,
|
||||
finishReason: data.choices?.[0]?.finish_reason ?? null,
|
||||
};
|
||||
} catch (err) {
|
||||
if (err instanceof LlmError) throw err;
|
||||
if (err instanceof Error && err.name === "AbortError") {
|
||||
|
||||
@@ -0,0 +1,134 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
accumulateUsage,
|
||||
combineSource,
|
||||
emptyUsage,
|
||||
hasUsage,
|
||||
normalizeUsage,
|
||||
type TokenUsage,
|
||||
} from "./usage.js";
|
||||
|
||||
function usage(partial: Partial<TokenUsage>): TokenUsage {
|
||||
return { ...emptyUsage(), ...partial };
|
||||
}
|
||||
|
||||
describe("normalizeUsage", () => {
|
||||
it("取 DeepSeek 顶层字段,包括缓存命中与未命中", () => {
|
||||
const { usage: result, source } = normalizeUsage({
|
||||
prompt_tokens: 1000,
|
||||
completion_tokens: 200,
|
||||
total_tokens: 1200,
|
||||
prompt_cache_hit_tokens: 800,
|
||||
prompt_cache_miss_tokens: 200,
|
||||
completion_tokens_details: { reasoning_tokens: 50 },
|
||||
});
|
||||
|
||||
expect(source).toBe("upstream");
|
||||
expect(result).toEqual({
|
||||
promptTokens: 1000,
|
||||
completionTokens: 200,
|
||||
totalTokens: 1200,
|
||||
cacheHitTokens: 800,
|
||||
cacheMissTokens: 200,
|
||||
reasoningTokens: 50,
|
||||
});
|
||||
});
|
||||
|
||||
it("OpenAI 风格的 prompt_tokens_details.cached_tokens 也能识别", () => {
|
||||
const { usage: result } = normalizeUsage({
|
||||
prompt_tokens: 500,
|
||||
completion_tokens: 100,
|
||||
prompt_tokens_details: { cached_tokens: 300 },
|
||||
});
|
||||
|
||||
expect(result.cacheHitTokens).toBe(300);
|
||||
// 未命中数缺失时用 prompt - hit 兜底推出
|
||||
expect(result.cacheMissTokens).toBe(200);
|
||||
});
|
||||
|
||||
it("total_tokens 缺失时用 prompt + completion 兜底", () => {
|
||||
const { usage: result } = normalizeUsage({ prompt_tokens: 10, completion_tokens: 5 });
|
||||
expect(result.totalTokens).toBe(15);
|
||||
});
|
||||
|
||||
it("缓存命中数大于 prompt 时不会算出负的未命中数", () => {
|
||||
const { usage: result } = normalizeUsage({
|
||||
prompt_tokens: 100,
|
||||
prompt_tokens_details: { cached_tokens: 150 },
|
||||
});
|
||||
expect(result.cacheMissTokens).toBe(0);
|
||||
});
|
||||
|
||||
it("非对象一律当成未上报,不抛错", () => {
|
||||
for (const raw of [undefined, null, "usage", 42, []]) {
|
||||
const { usage: result, source } = normalizeUsage(raw);
|
||||
expect(source).toBe("missing");
|
||||
expect(hasUsage(result)).toBe(false);
|
||||
}
|
||||
});
|
||||
|
||||
it("负值与非数字字段按未上报处理,不猜值", () => {
|
||||
const { usage: result, source } = normalizeUsage({
|
||||
prompt_tokens: -5,
|
||||
completion_tokens: "abc",
|
||||
});
|
||||
expect(source).toBe("missing");
|
||||
expect(result.promptTokens).toBeNull();
|
||||
expect(result.completionTokens).toBeNull();
|
||||
});
|
||||
|
||||
it("明确上报 0 与未上报是两种结果", () => {
|
||||
const reportedZero = normalizeUsage({ prompt_tokens: 0, completion_tokens: 0 });
|
||||
expect(reportedZero.source).toBe("upstream");
|
||||
expect(reportedZero.usage.promptTokens).toBe(0);
|
||||
|
||||
const missing = normalizeUsage({});
|
||||
expect(missing.source).toBe("missing");
|
||||
expect(missing.usage.promptTokens).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("accumulateUsage", () => {
|
||||
it("累加各次尝试的用量", () => {
|
||||
const result = accumulateUsage([
|
||||
usage({ promptTokens: 100, completionTokens: 20, totalTokens: 120 }),
|
||||
usage({ promptTokens: 150, completionTokens: 30, totalTokens: 180 }),
|
||||
]);
|
||||
|
||||
expect(result.promptTokens).toBe(250);
|
||||
expect(result.completionTokens).toBe(50);
|
||||
expect(result.totalTokens).toBe(300);
|
||||
});
|
||||
|
||||
it("某次尝试没上报的字段按 0 计,但全都没上报时保持 null", () => {
|
||||
const result = accumulateUsage([
|
||||
usage({ promptTokens: 100 }),
|
||||
usage({}),
|
||||
]);
|
||||
|
||||
expect(result.promptTokens).toBe(100);
|
||||
// 两次都没上报的字段不能被算成 0
|
||||
expect(result.completionTokens).toBeNull();
|
||||
expect(result.reasoningTokens).toBeNull();
|
||||
});
|
||||
|
||||
it("空数组返回全 null", () => {
|
||||
expect(hasUsage(accumulateUsage([]))).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("combineSource", () => {
|
||||
it("只要有真实上游数据就标 upstream", () => {
|
||||
expect(combineSource(["missing", "upstream", "missing"])).toBe("upstream");
|
||||
});
|
||||
|
||||
it("没有 upstream 但有估算时标 estimated", () => {
|
||||
expect(combineSource(["missing", "estimated"])).toBe("estimated");
|
||||
});
|
||||
|
||||
it("全为 missing 时标 missing", () => {
|
||||
expect(combineSource(["missing", "missing"])).toBe("missing");
|
||||
expect(combineSource([])).toBe("missing");
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,161 @@
|
||||
/**
|
||||
* Token 用量归一化与跨尝试累加。
|
||||
*
|
||||
* 设计要点:
|
||||
* - **null 与 0 是两回事**:null 表示上游根本没上报 usage,0 表示上游明确说这次用了 0。
|
||||
* 面板上「未上报」与「0 token」必须能分辨,否则上游一改返回结构,用量会静默变成 0 而不是暴露出来。
|
||||
* - **按厂商字段归一**:DeepSeek 把缓存命中放在顶层 `prompt_cache_hit_tokens`,
|
||||
* OpenAI 兼容实现放在 `prompt_tokens_details.cached_tokens`,两者都取;
|
||||
* 未命中数缺失时用 `prompt_tokens - cacheHit` 兜底推出。
|
||||
* - **跨尝试累加**:一个任务重试 N 次就是 N 次计费,失败尝试若已产生 token 同样要算
|
||||
* (例如上游返回 200 但内容为空)。累加时 null 视为 0,但「所有尝试都没上报」必须保持 null。
|
||||
*/
|
||||
|
||||
/** 一次 LLM 调用的 token 明细;字段为 null 表示上游未上报该维度 */
|
||||
export interface TokenUsage {
|
||||
promptTokens: number | null;
|
||||
completionTokens: number | null;
|
||||
totalTokens: number | null;
|
||||
/** 命中上下文缓存的输入 token(计价明显低于未命中) */
|
||||
cacheHitTokens: number | null;
|
||||
/** 未命中缓存的输入 token */
|
||||
cacheMissTokens: number | null;
|
||||
/** 思考模式产生的推理 token,已含在 completionTokens 内 */
|
||||
reasoningTokens: number | null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 用量的来源,用于区分「上游真实上报」与「本地兜底」。
|
||||
* `missing` 占比升高说明上游改了返回结构,是需要告警的信号。
|
||||
*/
|
||||
export type UsageSource = "upstream" | "estimated" | "missing";
|
||||
|
||||
export interface UsageSnapshot {
|
||||
usage: TokenUsage;
|
||||
source: UsageSource;
|
||||
}
|
||||
|
||||
const TOKEN_FIELDS = [
|
||||
"promptTokens",
|
||||
"completionTokens",
|
||||
"totalTokens",
|
||||
"cacheHitTokens",
|
||||
"cacheMissTokens",
|
||||
"reasoningTokens",
|
||||
] as const satisfies readonly (keyof TokenUsage)[];
|
||||
|
||||
export function emptyUsage(): TokenUsage {
|
||||
return {
|
||||
promptTokens: null,
|
||||
completionTokens: null,
|
||||
totalTokens: null,
|
||||
cacheHitTokens: null,
|
||||
cacheMissTokens: null,
|
||||
reasoningTokens: null,
|
||||
};
|
||||
}
|
||||
|
||||
export function hasUsage(usage: TokenUsage): boolean {
|
||||
return TOKEN_FIELDS.some((field) => usage[field] !== null);
|
||||
}
|
||||
|
||||
/** 只接受非负整数;负值、NaN、非数字一律当「未上报」,不要猜 */
|
||||
function nonNegativeInt(value: unknown): number | null {
|
||||
if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return null;
|
||||
return Math.floor(value);
|
||||
}
|
||||
|
||||
function firstPresent(...values: Array<number | null>): number | null {
|
||||
for (const value of values) {
|
||||
if (value !== null) return value;
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
function readPath(source: Record<string, unknown>, path: string): number | null {
|
||||
let current: unknown = source;
|
||||
for (const key of path.split(".")) {
|
||||
if (current === null || typeof current !== "object") return null;
|
||||
current = (current as Record<string, unknown>)[key];
|
||||
}
|
||||
return nonNegativeInt(current);
|
||||
}
|
||||
|
||||
/**
|
||||
* 把上游响应里的 `usage` 对象归一化成 {@link TokenUsage}。
|
||||
*
|
||||
* 传入任何非对象(undefined、null、字符串)都返回全 null 且来源为 `missing`,
|
||||
* 让调用方无需自己判空。
|
||||
*/
|
||||
export function normalizeUsage(raw: unknown): UsageSnapshot {
|
||||
if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
|
||||
return { usage: emptyUsage(), source: "missing" };
|
||||
}
|
||||
const source = raw as Record<string, unknown>;
|
||||
|
||||
// Anthropic 风格的 input/output_tokens 一并兼容,换供应商时不用改这里
|
||||
const promptTokens = firstPresent(
|
||||
readPath(source, "prompt_tokens"),
|
||||
readPath(source, "input_tokens"),
|
||||
);
|
||||
const completionTokens = firstPresent(
|
||||
readPath(source, "completion_tokens"),
|
||||
readPath(source, "output_tokens"),
|
||||
);
|
||||
const totalTokens = firstPresent(
|
||||
readPath(source, "total_tokens"),
|
||||
promptTokens !== null && completionTokens !== null ? promptTokens + completionTokens : null,
|
||||
);
|
||||
const cacheHitTokens = firstPresent(
|
||||
readPath(source, "prompt_cache_hit_tokens"),
|
||||
readPath(source, "prompt_tokens_details.cached_tokens"),
|
||||
readPath(source, "input_tokens_details.cached_tokens"),
|
||||
);
|
||||
const cacheMissTokens = firstPresent(
|
||||
readPath(source, "prompt_cache_miss_tokens"),
|
||||
// 上游只给总数与命中数时,相减即未命中数;钳到 0 避免上游字段不一致时算出负数
|
||||
promptTokens !== null && cacheHitTokens !== null
|
||||
? Math.max(0, promptTokens - cacheHitTokens)
|
||||
: null,
|
||||
);
|
||||
const reasoningTokens = readPath(source, "completion_tokens_details.reasoning_tokens");
|
||||
|
||||
const usage: TokenUsage = {
|
||||
promptTokens,
|
||||
completionTokens,
|
||||
totalTokens,
|
||||
cacheHitTokens,
|
||||
cacheMissTokens,
|
||||
reasoningTokens,
|
||||
};
|
||||
return { usage, source: hasUsage(usage) ? "upstream" : "missing" };
|
||||
}
|
||||
|
||||
/**
|
||||
* 累加多次尝试的用量。
|
||||
*
|
||||
* 每个字段独立判断:只要有任意一次上报了该字段就求和(未上报的那几次按 0 计),
|
||||
* 全部都没上报才返回 null。这样「重试 3 次只有第 2 次拿到 usage」不会被算成 0。
|
||||
*/
|
||||
export function accumulateUsage(snapshots: TokenUsage[]): TokenUsage {
|
||||
const result = emptyUsage();
|
||||
for (const field of TOKEN_FIELDS) {
|
||||
const present = snapshots
|
||||
.map((snapshot) => snapshot[field])
|
||||
.filter((value): value is number => value !== null);
|
||||
result[field] = present.length > 0 ? present.reduce((sum, value) => sum + value, 0) : null;
|
||||
}
|
||||
return result;
|
||||
}
|
||||
|
||||
/**
|
||||
* 合并多次尝试的来源标记。
|
||||
*
|
||||
* 只要有一次拿到真实上游数据就标 `upstream`——部分上报仍比完全没有数据可信,
|
||||
* 把它降级成 `estimated` 会让「上游改结构」这个信号被淹没。
|
||||
*/
|
||||
export function combineSource(sources: UsageSource[]): UsageSource {
|
||||
if (sources.includes("upstream")) return "upstream";
|
||||
if (sources.includes("estimated")) return "estimated";
|
||||
return "missing";
|
||||
}
|
||||
Reference in New Issue
Block a user