feat: 用量归属支持 callerRef 透传

- POST /ai/tasks 接受顶层可选 callerRef(限 64 字符),不进入 params、不参与幂等键、不进 prompt
- 结算时写进用量记录,lpt-be 据此做用户维度报表
- 复用已有任务时沿用原归属:那次 LLM 调用只发生一次,账算在原调用方头上
This commit is contained in:
2026-10-10 20:08:51 +08:00
parent 935f4781a4
commit 4aff5c03fe
9 changed files with 240 additions and 2 deletions
+16 -1
View File
@@ -64,9 +64,24 @@ lpt-ai/src/
峰时窗口按 UTC 判定(`01:00-04:00`、`06:00-10:00`,周一至周五),谷时 = 峰时 × 0.5。
计价结果在结算时**冻结进日志快照**,改价不会重算历史账。
- `admin/reporter.ts`:把用量推给 lpt-be(长期账本)。上报失败先落本地 outbox 再重试,
幂等靠 `record_id` 唯一索引。未配置 `LPT_AI_REPORT_URL` 时为空操作。
幂等靠 `record_id` 唯一索引;4xx 属于确定性拒绝,丢弃这批并计数,不无限重试。
未配置 `LPT_AI_REPORT_URL` 时为空操作。
- **权威口径在 lpt-be 的 MySQL**;本地面板只是最近 500 条的调试视图。
### 用量归属(callerRef)
lpt-ai 不知道调用方是谁,所以归属标记由调用方带过来:`POST /ai/tasks` 接受顶层可选字段
`callerRef`(lpt-be 传的是用户 id),结算时原样写进用量记录,lpt-be 据此做用户维度报表。
三条硬约束,改动时必须守住:
1. **不放进 `params`** —— 会污染 prompt 模板的输入;
2. **不参与幂等键** —— 否则同一份输入会因为调用方不同而重复调 LLM;
3. **不进入 prompt** —— 它只是记账标记。
复用已有任务时**沿用原任务的 `callerRef`**:那次 LLM 调用只发生了一次,账算在原调用方头上;
复用方没有产生新的 token 消耗,也不会有新的用量记录。
> `/admin` 用 `?token=…` 首次打开时会换发 `HttpOnly` cookie,否则面板 HTML 与它内部的
> `fetch` 是两个独立请求,内部请求会全部 401。详见 `roles/security-and-degradation.md`。
+5
View File
@@ -120,6 +120,11 @@ describe("toUsageRecord", () => {
expect(record.model).toBe("");
});
it("归属标记原样带上;没传时显式写 null", () => {
expect(toUsageRecord(entry({ callerRef: "U-123" })).callerRef).toBe("U-123");
expect(toUsageRecord(entry()).callerRef).toBeNull();
});
it("必填字段永远非空,否则 lpt-be 会把整批上报判 400", () => {
// 契约 1 的必填项:lpt-be 侧 @NotBlank 的字段不能是空串,@NotNull 的字段不能缺。
// 尤其是 /fetch-title 的 model——它合法地是空串,所以 lpt-be 那边用的是 @NotNull。
+3
View File
@@ -23,6 +23,8 @@ export interface UsageRecord {
occurredAt: string;
taskType: string;
taskId: string | null;
/** 归属标记(lpt-be 传的用户 id);lpt-be 把它落到 ai_usage_records.user_id */
callerRef: string | null;
model: string;
attempts: number;
isLlmCall: boolean;
@@ -91,6 +93,7 @@ export function toUsageRecord(entry: LogEntry): UsageRecord {
occurredAt: entry.timestamp,
taskType: entry.taskType ?? entry.endpoint,
taskId: entry.taskId ?? null,
callerRef: entry.callerRef ?? null,
model: entry.model,
attempts: entry.attempts ?? 1,
isLlmCall: entry.isLlmCall,
+1
View File
@@ -185,6 +185,7 @@ async function toggleDetail(id, el) {
let txt = '=== lpt-ai 请求日志 ===\\n';
txt += '端点: '+(log.endpoint||'')+'\\n';
txt += '模型: '+(log.model||'')+'\\n';
txt += '归属: '+(log.callerRef||'未归属')+'\\n';
txt += '耗时: '+log.durationMs+'ms\\n';
txt += '状态: '+log.status+'\\n';
if (log.attempts != null) txt += '调用次数: '+log.attempts+'\\n';
+4
View File
@@ -31,6 +31,8 @@ export interface LogEntry {
taskType?: string;
/** 任务标识,便于把面板上的一条日志对回具体任务 */
taskId?: string;
/** 归属标记(lpt-be 传的用户 id);为空表示调用方没传或为独立调用 */
callerRef?: string;
model: string;
/** 本次请求实际发起的 LLM 调用次数(含失败重试);重试会重复计费 */
attempts?: number;
@@ -57,6 +59,7 @@ export interface LogSummary {
timestamp: string;
endpoint: string;
taskType?: string;
callerRef?: string;
model: string;
attempts?: number;
isLlmCall: boolean;
@@ -140,6 +143,7 @@ export class LogStore {
timestamp: entry.timestamp,
endpoint: entry.endpoint,
...(entry.taskType !== undefined ? { taskType: entry.taskType } : {}),
...(entry.callerRef !== undefined ? { callerRef: entry.callerRef } : {}),
model: entry.model,
...(entry.attempts !== undefined ? { attempts: entry.attempts } : {}),
isLlmCall: entry.isLlmCall,
+127
View File
@@ -0,0 +1,127 @@
import { mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import Fastify from "fastify";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { aiRoutes } from "./ai.js";
import { getTask } from "../task-queue.js";
const originalDataDir = process.env.LPT_AI_DATA_DIR;
const originalKey = process.env.LLM_API_KEY;
const originalRateLimit = process.env.LPT_AI_RATE_LIMIT;
let workDir: string;
beforeEach(() => {
// 面板日志会落盘,必须指向临时目录,否则会清掉开发者真实的面板数据
workDir = mkdtempSync(join(tmpdir(), "lpt-ai-routes-"));
process.env.LPT_AI_DATA_DIR = workDir;
// 不配 Key:任务会以「LLM 不可用」快速失败,用例不需要真调 LLM
delete process.env.LLM_API_KEY;
process.env.LPT_AI_RATE_LIMIT = "10000";
});
afterEach(() => {
for (const [key, value] of [
["LPT_AI_DATA_DIR", originalDataDir],
["LLM_API_KEY", originalKey],
["LPT_AI_RATE_LIMIT", originalRateLimit],
] as const) {
if (value === undefined) {
delete process.env[key];
} else {
process.env[key] = value;
}
}
rmSync(workDir, { recursive: true, force: true });
});
async function buildApp() {
const app = Fastify();
await app.register(aiRoutes);
await app.ready();
return app;
}
function submit(app: Awaited<ReturnType<typeof buildApp>>, body: unknown) {
return app.inject({
method: "POST",
url: "/ai/tasks",
payload: body as Record<string, unknown>,
});
}
describe("POST /ai/tasks 的 callerRef(用量归属)", () => {
it("带归属提交时落到任务记录上,供结算写进用量记录", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
callerRef: "U-123",
});
expect(response.statusCode).toBe(201);
const { taskId } = JSON.parse(response.body) as { taskId: string };
expect(getTask(taskId)?.callerRef).toBe("U-123");
await app.close();
});
it("不传归属时任务记录上没有该字段", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
});
const { taskId } = JSON.parse(response.body) as { taskId: string };
expect(getTask(taskId)?.callerRef).toBeUndefined();
await app.close();
});
it("空白归属视为未传,不写空字符串", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
callerRef: " ",
});
const { taskId } = JSON.parse(response.body) as { taskId: string };
expect(getTask(taskId)?.callerRef).toBeUndefined();
await app.close();
});
it("超过 64 字符被拒:它会落进日志与数据库列,限长比让库截断安全", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
callerRef: "x".repeat(65),
});
expect(response.statusCode).toBe(400);
expect(JSON.parse(response.body).error).toContain("64");
await app.close();
});
it("非字符串被拒,避免把对象写进归属列", async () => {
const app = await buildApp();
const response = await submit(app, {
type: "guidance",
params: { taskName: "t", concept: "c", history: [] },
callerRef: { userId: "U-1" },
});
expect(response.statusCode).toBe(400);
await app.close();
});
it("归属不影响参数校验:type 非法仍然优先报错", async () => {
const app = await buildApp();
const response = await submit(app, { type: "nope", params: {}, callerRef: "U-1" });
expect(response.statusCode).toBe(400);
expect(JSON.parse(response.body).error).toContain("无效的 type");
await app.close();
});
});
+22 -1
View File
@@ -10,6 +10,14 @@ import { safeFetchText, UnsafeUrlError } from "../utils/ssrf-guard.js";
import { RateLimiter, intFromEnv } from "../utils/rate-limit.js";
import { checkToken } from "../utils/auth.js";
/**
* 归属标记的最大长度。
*
* 它会落进日志与 lpt-be 的 `ai_usage_records.user_id`(VARCHAR(255)),
* 在入口限长比让数据库截断更安全。
*/
const MAX_CALLER_REF_LENGTH = 64;
export async function aiRoutes(app: FastifyInstance): Promise<void> {
const config = loadConfig();
@@ -52,9 +60,11 @@ export async function aiRoutes(app: FastifyInstance): Promise<void> {
idempotencyKey?: string;
/** 可选:跳过结果复用,强制重新生成 */
force?: boolean;
/** 可选:归属标记(lpt-be 传用户 id),原样写进用量记录;不参与幂等键 */
callerRef?: string;
};
}>("/ai/tasks", async (request, reply) => {
const { type, params, idempotencyKey, force } = request.body ?? {};
const { type, params, idempotencyKey, force, callerRef } = request.body ?? {};
const decision = taskLimiter.check(clientKey(request));
if (!decision.allowed) {
@@ -71,12 +81,23 @@ export async function aiRoutes(app: FastifyInstance): Promise<void> {
if (!params || typeof params !== "object") {
return reply.status(400).send({ error: "params 必须为非空对象" });
}
// 归属标记是 opaque 字符串,但必须限长:它会落进日志与数据库列(VARCHAR(64))
if (callerRef !== undefined && callerRef !== null) {
if (typeof callerRef !== "string" || callerRef.length > MAX_CALLER_REF_LENGTH) {
return reply
.status(400)
.send({ error: `callerRef 必须是不超过 ${MAX_CALLER_REF_LENGTH} 字符的字符串` });
}
}
const created = createTask(type as TaskType, params as Record<string, unknown>, {
...(typeof idempotencyKey === "string" && idempotencyKey.trim().length > 0
? { idempotencyKey }
: {}),
...(force === true ? { force: true } : {}),
...(typeof callerRef === "string" && callerRef.trim().length > 0
? { callerRef: callerRef.trim() }
: {}),
});
// 固定返回 201:Java 端 AiServiceClient 把非 201 当作提交失败,
+46
View File
@@ -654,6 +654,52 @@ describe("用量归集", () => {
});
});
describe("callerRef(用量归属)", () => {
it("落到任务记录上,供结算时写进用量日志", async () => {
const queue = makeQueue({}, async () => ({ ok: true }));
const created = queue.create(
"aggregate-report",
{ taskName: "t", fragments: [] },
{ callerRef: "U-123" },
);
await queue.drain();
expect(queue.get(created.taskId)?.callerRef).toBe("U-123");
queue.stop();
});
it("不传时不写该字段,避免出现空字符串归属", async () => {
const queue = makeQueue({}, async () => ({ ok: true }));
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
await queue.drain();
expect(queue.get(created.taskId)?.callerRef).toBeUndefined();
queue.stop();
});
it("复用已有任务时沿用原归属,不被后来的调用方覆盖", async () => {
// 同类型同参数会被复用,而那次 LLM 调用只发生了一次,账算在原调用方头上;
// 复用方没有产生新的 token 消耗,也不会有新的用量记录。
const queue = makeQueue({}, async () => ({ ok: true }));
const params = { taskName: "t", fragments: [{ content: "same" }] };
const first = queue.create("aggregate-report", params, { callerRef: "U-1" });
await queue.drain();
const second = queue.create("aggregate-report", params, { callerRef: "U-2" });
expect(second.reused).toBe(true);
expect(second.taskId).toBe(first.taskId);
expect(queue.get(first.taskId)?.callerRef).toBe("U-1");
queue.stop();
});
it("不参与幂等键:同一输入带上不同归属仍然复用同一个任务", () => {
// 若 callerRef 进了键,同一份输入会因为调用方不同而重复调 LLM,白花钱
const withRef = computeTaskKey("aggregate-report", { taskName: "t" });
expect(computeTaskKey("aggregate-report", { taskName: "t" })).toBe(withRef);
});
});
describe("classifyLlmError", () => {
it("按状态码归成可聚合的分类", () => {
expect(classifyLlmError(new LlmError("超时", 504))).toBe("timeout");
+16
View File
@@ -37,6 +37,13 @@ export interface TaskRecord {
error?: string;
/** 已尝试次数(含首次),便于排查重试情况 */
attempts: number;
/**
* 调用方打的归属标记(lpt-be 传的是用户 id)。
*
* opaque 字符串,lpt-ai 不解释它的含义,只在结算时原样写进用量记录。
* 刻意不放进 `params`:那会污染 prompt 模板的输入,也会把幂等键算错。
*/
callerRef?: string;
/**
* 跨所有尝试累加的 token 用量。
*
@@ -57,6 +64,13 @@ export interface CreateTaskOptions {
idempotencyKey?: string;
/** 跳过复用,强制新建任务(用户主动「重新生成」时用) */
force?: boolean;
/**
* 归属标记(lpt-be 传用户 id),结算时原样写进用量记录。
*
* 复用已有任务时**不会**覆盖原任务的标记:那次 LLM 调用只发生了一次,
* 账算在原调用方头上;复用方没有产生新的 token 消耗。
*/
callerRef?: string;
}
export interface CreateTaskResult {
@@ -210,6 +224,7 @@ export class TaskQueue {
status: "pending",
attempts: 0,
createdAt: new Date(this.now()).toISOString(),
...(options.callerRef ? { callerRef: options.callerRef } : {}),
};
this.records.set(id, task);
this.keyIndex.set(key, id);
@@ -386,6 +401,7 @@ export class TaskQueue {
endpoint: `/ai/tasks#${task.type}`,
taskType: task.type,
taskId: task.id,
...(task.callerRef ? { callerRef: task.callerRef } : {}),
model: config.model,
attempts: task.attempts,
isLlmCall: true,