feat: 采集 LLM token 用量并上报 lpt-be

- 客户端解析上游 usage(含 DeepSeek 缓存命中/未命中),跨重试累加
- 新增计价表(三档单价 + 峰谷时段),费用在结算时冻结
- 新增用量上报与本地 outbox 重试;4xx 判定为确定性拒绝,不无限重试
- 面板补充 Token/费用/调用次数与计价快照
- 顺带修复面板内联脚本转义错误(模板字面量吃掉 \n 与 \',面板一直空白)
This commit is contained in:
2026-10-10 18:46:01 +08:00
parent fd1193a66f
commit 935f4781a4
24 changed files with 2632 additions and 65 deletions
+74
View File
@@ -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
View File
@@ -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") {
+134
View File
@@ -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");
});
});
+161
View File
@@ -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";
}