perf: LLM 按 prompt 长度自适应思考强度

This commit is contained in:
2026-10-10 17:53:41 +08:00
parent 09d16dfb98
commit fd1193a66f
9 changed files with 321 additions and 6 deletions
+12
View File
@@ -7,6 +7,18 @@ LLM_MODEL=deepseek-flash
# 请求超时(毫秒)
LLM_TIMEOUT_MS=60000
# ---- 思考强度自适应(reasoning_effort)----
# DeepSeek 的 reasoning_effort 缺省是 high,不显式指定就每次满档思考。
# 这里按 prompt 总字符数(所有 message 正文之和)选档,短输入直接 none 关掉思考。
# 显式写 false 才关闭自适应(回到供应商默认);换到不支持该字段的供应商时用得上。
LPT_AI_REASONING_ENABLED=true
# 长度达到该值起用 low;低于它一律 none(不思考)
LPT_AI_REASONING_LOW_AT=500
# 长度达到该值起用 high
LPT_AI_REASONING_HIGH_AT=2000
# 长度达到该值起用 max
LPT_AI_REASONING_MAX_AT=8000
# 服务端口
PORT=5199
+12
View File
@@ -26,6 +26,7 @@ lpt-ai/src/
├── routes/ai.ts → AI 路由(health, tasks, fetch-title)
├── llm/
│ ├── client.ts → LLM 客户端(DeepSeek 接口)
│ ├── thinking.ts → 按 prompt 长度选思考强度(reasoning_effort)
│ ├── retry.ts → 退避重试(哪些错误可重试、等多久)
│ ├── prompts.ts → Prompt 模板(3 种任务类型)
│ └── prompts.test.ts
@@ -54,6 +55,11 @@ lpt-ai/src/
| `aggregate-report` | 残片聚合为学习报告 | 0.3 | 2048 |
| `generate-mind-map` | 从报告/残片生成思维导图大纲 | 0.3 | 4096 |
| `compare-recall` | 用户回忆 vs 标准导图语义对比 | 0.2 | 4096 |
| `guidance` | 学习引导单轮追问 | 0.7 | 1024 |
> 思考强度(`reasoning_effort`)不按任务类型固定,而是按 **prompt 总字符数**(所有 message 正文之和)自适应:
> 低于 `LPT_AI_REASONING_LOW_AT` → `none`(直接关掉思考),之后依次 `low` / `high`,超过 `LPT_AI_REASONING_MAX_AT` → `max`。
> 原因是 DeepSeek 缺省 `high`,不显式指定则短输入也会满档思考。映射实现在 `src/llm/thinking.ts`,阈值见 `.env.example`。
## LLM 配置
@@ -64,6 +70,12 @@ LLM_MODEL=deepseek-flash
LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时
PORT=5199
# 思考强度自适应(完整注释见 .env.example)
LPT_AI_REASONING_ENABLED=true # 显式 false 才关闭自适应,回到供应商默认
LPT_AI_REASONING_LOW_AT=500 # 达到该长度起用 low,低于则为 none
LPT_AI_REASONING_HIGH_AT=2000 # 达到该长度起用 high
LPT_AI_REASONING_MAX_AT=8000 # 达到该长度起用 max
# 任务队列(完整注释见 .env.example)
LPT_AI_CONCURRENCY=2 # Worker 池并发度
LPT_AI_MAX_ATTEMPTS=3 # 单任务总尝试次数(含首次)
+4 -1
View File
@@ -1,7 +1,7 @@
# 任务队列
- **功能**:定义 lpt-ai 异步任务队列(Worker 池、退避重试、相同输入幂等复用、TTL 清理)的行为与不可改契约。
- **何时用**:改动 `/ai/tasks` 的提交/轮询、并发度、重试、幂等复用、TTL 清理、管理面板日志,或调整任务响应契约时。
- **何时用**:改动 `/ai/tasks` 的提交/轮询、并发度、重试、幂等复用、TTL 清理、管理面板日志,或调整任务响应契约与单次调用参数(温度 / 思考强度)时。
## 任务队列设计
@@ -17,6 +17,9 @@
- 请求体传 `force: true` 可跳过复用(用户主动「重新生成」)
- 也可传 `idempotencyKey` 显式指定幂等键
- TTL 清理:按 `LPT_AI_CLEANUP_MS` 周期移除过期记录,同时清理幂等索引。
- **单次调用参数**:温度与输出上限按任务类型固定;思考强度(`reasoning_effort`)按 prompt 总字符数自适应,
短输入直接 `none` 关掉思考(DeepSeek 缺省 `high`,不显式指定就会满档思考)。
调用参数不参与幂等键,改阈值不会让已有缓存失效。映射实现在 `src/llm/thinking.ts`。
- 异常隔离:单个任务失败不影响后续任务。
- 管理面板日志:复用 `logStore`,记录最近 200 条请求/响应。
+66
View File
@@ -0,0 +1,66 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { chat, type LlmConfig } from "./client.js";
/**
* 只验证「请求体契约」:思考强度要真的写进 `reasoning_effort`,
* 不传时不能凭空加上该字段(否则换供应商会被当成非法参数)。
*/
const llmConfig: LlmConfig = {
apiUrl: "https://example.invalid/v1/chat/completions",
apiKey: "test-key",
model: "deepseek-flash",
timeoutMs: 5_000,
};
function mockFetchOnce() {
const fetchMock = vi.fn().mockResolvedValue({
ok: true,
json: async () => ({ choices: [{ message: { content: "ok" } }] }),
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>;
}
afterEach(() => {
vi.unstubAllGlobals();
});
describe("chat 请求体", () => {
it("传入 reasoningEffort 时写进 reasoning_effort", async () => {
const fetchMock = mockFetchOnce();
await chat(llmConfig, [{ role: "user", content: "hi" }], {
temperature: 0.2,
maxTokens: 1024,
reasoningEffort: "low",
});
expect(bodyOf(fetchMock)).toMatchObject({
model: "deepseek-flash",
temperature: 0.2,
max_tokens: 1024,
stream: false,
reasoning_effort: "low",
});
});
it("none 也要显式发送,用于关闭思考模式", async () => {
const fetchMock = mockFetchOnce();
await chat(llmConfig, [{ role: "user", content: "hi" }], { reasoningEffort: "none" });
expect(bodyOf(fetchMock).reasoning_effort).toBe("none");
});
it("不传 reasoningEffort 时不带该字段,交回供应商默认", async () => {
const fetchMock = mockFetchOnce();
await chat(llmConfig, [{ role: "user", content: "hi" }]);
expect(bodyOf(fetchMock)).not.toHaveProperty("reasoning_effort");
});
});
+13 -1
View File
@@ -7,11 +7,21 @@
* - 超时保护,避免长时间挂起
*/
import type { ReasoningEffort } from "./thinking.js";
export interface ChatMessage {
role: "system" | "user" | "assistant";
content: string;
}
/** 单次调用的采样参数:温度与输出上限按任务类型定,思考强度按 prompt 长度定 */
export interface ChatOptions {
temperature?: number;
maxTokens?: number;
/** 思考强度;不传时不带 `reasoning_effort`,由供应商按自己的默认值处理 */
reasoningEffort?: ReasoningEffort;
}
export interface LlmConfig {
apiUrl: string;
apiKey: string;
@@ -76,7 +86,7 @@ export function parseRetryAfter(value: string | null, now: number = Date.now()):
export async function chat(
config: LlmConfig,
messages: ChatMessage[],
options?: { temperature?: number; maxTokens?: number },
options?: ChatOptions,
): Promise<string> {
if (!isAvailable(config)) {
throw new LlmError("LLM API Key 未配置", 503);
@@ -98,6 +108,8 @@ export async function chat(
temperature: options?.temperature ?? 0.3,
max_tokens: options?.maxTokens ?? 2048,
stream: false,
// 思考强度交给调用方按内容长度决定;不传表示由供应商默认(DeepSeek 为 high)
...(options?.reasoningEffort ? { reasoning_effort: options.reasoningEffort } : {}),
}),
signal: controller.signal,
});
+87
View File
@@ -0,0 +1,87 @@
import { describe, expect, it } from "vitest";
import {
loadThinkingConfig,
promptLength,
reasoningEffortFor,
type ThinkingConfig,
} from "./thinking.js";
const config = (overrides: Partial<ThinkingConfig> = {}): ThinkingConfig => ({
enabled: true,
lowAt: 500,
highAt: 2_000,
maxAt: 8_000,
...overrides,
});
describe("loadThinkingConfig", () => {
it("缺省值可用:开启自适应,500 / 2000 / 8000 分档", () => {
expect(loadThinkingConfig({})).toEqual({
enabled: true,
lowAt: 500,
highAt: 2_000,
maxAt: 8_000,
});
});
it("环境变量可覆盖阈值", () => {
const loaded = loadThinkingConfig({
LPT_AI_REASONING_LOW_AT: "100",
LPT_AI_REASONING_HIGH_AT: "900",
LPT_AI_REASONING_MAX_AT: "5000",
});
expect(loaded).toMatchObject({ lowAt: 100, highAt: 900, maxAt: 5_000 });
});
it("非法阈值回退到缺省", () => {
const loaded = loadThinkingConfig({
LPT_AI_REASONING_LOW_AT: "-1",
LPT_AI_REASONING_HIGH_AT: "abc",
});
expect(loaded.lowAt).toBe(500);
expect(loaded.highAt).toBe(2_000);
});
it("只有显式 false 才关闭自适应,空值与其他取值都保持开启", () => {
expect(loadThinkingConfig({ LPT_AI_REASONING_ENABLED: "false" }).enabled).toBe(false);
expect(loadThinkingConfig({ LPT_AI_REASONING_ENABLED: "False" }).enabled).toBe(false);
expect(loadThinkingConfig({ LPT_AI_REASONING_ENABLED: "" }).enabled).toBe(true);
expect(loadThinkingConfig({ LPT_AI_REASONING_ENABLED: "0" }).enabled).toBe(true);
});
});
describe("promptLength", () => {
it("累加所有 message 的正文长度", () => {
expect(
promptLength([
{ role: "system", content: "abcd" },
{ role: "user", content: "efg" },
]),
).toBe(7);
});
it("空消息列表为 0", () => {
expect(promptLength([])).toBe(0);
});
});
describe("reasoningEffortFor", () => {
it("按长度落在对应档位", () => {
expect(reasoningEffortFor(0, config())).toBe("none");
expect(reasoningEffortFor(499, config())).toBe("none");
expect(reasoningEffortFor(500, config())).toBe("low");
expect(reasoningEffortFor(1_999, config())).toBe("low");
expect(reasoningEffortFor(2_000, config())).toBe("high");
expect(reasoningEffortFor(7_999, config())).toBe("high");
expect(reasoningEffortFor(8_000, config())).toBe("max");
expect(reasoningEffortFor(100_000, config())).toBe("max");
});
it("阈值写反时按升序兜底,仍保持单调不降", () => {
const reversed = config({ lowAt: 5_000, highAt: 100, maxAt: 200 });
expect(reasoningEffortFor(50, reversed)).toBe("none");
expect(reasoningEffortFor(100, reversed)).toBe("low");
expect(reasoningEffortFor(200, reversed)).toBe("high");
expect(reasoningEffortFor(5_000, reversed)).toBe("max");
});
});
+74
View File
@@ -0,0 +1,74 @@
/**
* 思考强度(reasoning_effort)自适应 —— 按 prompt 内容长度选档。
*
* 背景:DeepSeek 的 `reasoning_effort` 缺省是 `high`,即不显式指定时每次都按满档思考。
* 残片聚合、单轮引导这类短输入根本不需要那么多思考,白付额度和延迟;
* 所以这里用一个统一口径(所有 message 正文字符数)决定档位,短文本直接 `none` 关掉思考。
*
* 契约:`reasoning_effort` 只作为调用参数随请求发送,**不进任务 params**,
* 因此不影响 `type + params` 幂等键。
*/
import type { ChatMessage } from "./client.js";
/** DeepSeek `reasoning_effort` 取值;`none` 表示关闭思考模式 */
export type ReasoningEffort = "none" | "low" | "high" | "max";
export interface ThinkingConfig {
/** 是否在请求里携带 `reasoning_effort`;换到不支持该字段的供应商时可关闭(回到供应商默认) */
enabled: boolean;
/** 长度达到该值起用 low;低于它一律 none(不思考) */
lowAt: number;
/** 长度达到该值起用 high */
highAt: number;
/** 长度达到该值起用 max */
maxAt: number;
}
const DEFAULT_LOW_AT = 500;
const DEFAULT_HIGH_AT = 2_000;
const DEFAULT_MAX_AT = 8_000;
function intFrom(value: string | undefined, fallback: number): number {
if (value === undefined || value.trim() === "") return fallback;
const parsed = Number(value);
return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
}
/** 只有显式写 `false`(不区分大小写)才关闭,避免部署里写错的空值把功能悄悄关掉 */
function boolFrom(value: string | undefined, fallback: boolean): boolean {
if (value === undefined || value.trim() === "") return fallback;
return value.trim().toLowerCase() !== "false";
}
export function loadThinkingConfig(env: NodeJS.ProcessEnv = process.env): ThinkingConfig {
return {
enabled: boolFrom(env.LPT_AI_REASONING_ENABLED, true),
lowAt: intFrom(env.LPT_AI_REASONING_LOW_AT, DEFAULT_LOW_AT),
highAt: intFrom(env.LPT_AI_REASONING_HIGH_AT, DEFAULT_HIGH_AT),
maxAt: intFrom(env.LPT_AI_REASONING_MAX_AT, DEFAULT_MAX_AT),
};
}
/** prompt 总字符数:所有 message 正文长度之和(system 说明与 user 素材都算) */
export function promptLength(messages: ChatMessage[]): number {
return messages.reduce((sum, message) => sum + message.content.length, 0);
}
/**
* 阈值必须严格递增,否则分档会出现「永远命中低档」的坑;
* 这里把写反或写重的配置按升序排一遍并去重兜底,宁可升档也不静默错档。
*/
function normalizeThresholds(config: ThinkingConfig): [number, number, number] {
const sorted = [config.lowAt, config.highAt, config.maxAt].sort((a, b) => a - b);
return [sorted[0], Math.max(sorted[1], sorted[0] + 1), Math.max(sorted[2], sorted[1] + 1)];
}
/** 按 prompt 长度选思考档位:越短越省,越长越深 */
export function reasoningEffortFor(length: number, config: ThinkingConfig): ReasoningEffort {
const [lowAt, highAt, maxAt] = normalizeThresholds(config);
if (length >= maxAt) return "max";
if (length >= highAt) return "high";
if (length >= lowAt) return "low";
return "none";
}
+33 -1
View File
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
import { LlmError } from "./llm/client.js";
import { parseReportDraft, TaskQueue, computeTaskKey, loadQueueConfig, type QueueConfig, type TaskRecord } from "./task-queue.js";
import { parseReportDraft, TaskQueue, computeTaskKey, callOptionsFor, loadQueueConfig, type QueueConfig, type TaskRecord } from "./task-queue.js";
/** 测试用队列:不碰真实 LLM、不写管理面板日志、不启定时器 */
function makeQueue(
@@ -56,6 +56,38 @@ describe("loadQueueConfig", () => {
});
});
describe("callOptionsFor", () => {
const thinking = { enabled: true, lowAt: 500, highAt: 2_000, maxAt: 8_000 };
it("短 prompt 关闭思考,但温度与输出上限仍按任务类型", () => {
const options = callOptionsFor("aggregate-report", [{ role: "user", content: "短" }], thinking);
expect(options.reasoningEffort).toBe("none");
expect(options.temperature).toBe(0.3);
expect(options.maxTokens).toBe(2048);
});
it("长 prompt 升到 max,任务类型基准参数不变", () => {
const options = callOptionsFor(
"generate-mind-map",
[{ role: "user", content: "x".repeat(9_000) }],
thinking,
);
expect(options.reasoningEffort).toBe("max");
expect(options.temperature).toBe(0.3);
expect(options.maxTokens).toBe(4096);
});
it("关闭自适应时不带 reasoningEffort,回退供应商默认", () => {
const options = callOptionsFor(
"compare-recall",
[{ role: "user", content: "x".repeat(9_000) }],
{ ...thinking, enabled: false },
);
expect(options.reasoningEffort).toBeUndefined();
expect(options.temperature).toBe(0.2);
});
});
describe("computeTaskKey", () => {
it("同输入得到同键", () => {
const a = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] });
+20 -3
View File
@@ -12,9 +12,10 @@
*/
import { randomUUID, createHash } from "node:crypto";
import { chat, isAvailable, loadConfig, LlmError, type ChatMessage } from "./llm/client.js";
import { chat, isAvailable, loadConfig, LlmError, type ChatMessage, type ChatOptions } from "./llm/client.js";
import { withRetry, isRetryableLlmError, type RetryOptions } from "./llm/retry.js";
import { aggregateReportPrompt, compareRecallPrompt, generateMindMapPrompt, guidancePrompt } from "./llm/prompts.js";
import { loadThinkingConfig, promptLength, reasoningEffortFor, type ThinkingConfig } from "./llm/thinking.js";
import { logStore } from "./admin/store.js";
// ---- 类型 ----
@@ -293,7 +294,7 @@ export class TaskQueue {
}
const messages = buildMessages(task);
const callOptions = callOptionsFor(task.type);
const callOptions = callOptionsFor(task.type, messages);
const retryOptions: RetryOptions = {
maxAttempts: this.config.maxAttempts,
@@ -378,13 +379,29 @@ export class TaskQueue {
// ---- 结果解析与 Prompt ----
function callOptionsFor(type: TaskType): { temperature: number; maxTokens: number } {
function baseCallOptions(type: TaskType): ChatOptions {
if (type === "compare-recall") return { temperature: 0.2, maxTokens: 4096 };
if (type === "generate-mind-map") return { temperature: 0.3, maxTokens: 4096 };
if (type === "guidance") return { temperature: 0.7, maxTokens: 1024 };
return { temperature: 0.3, maxTokens: 2048 };
}
/**
* 单次调用参数:温度与输出上限按任务类型固定,思考强度按 prompt 总长度自适应。
*
* 短输入(几句碎片、单轮引导)直接 `none` 关掉思考,不再跟随供应商的默认 `high`,
* 避免为一点点内容付满档思考的额度与延迟;阈值全部走 `LPT_AI_REASONING_*`。
*/
export function callOptionsFor(
type: TaskType,
messages: ChatMessage[],
thinking: ThinkingConfig = loadThinkingConfig(),
): ChatOptions {
const base = baseCallOptions(type);
if (!thinking.enabled) return base;
return { ...base, reasoningEffort: reasoningEffortFor(promptLength(messages), thinking) };
}
/** 把模型原文转成结构化结果 */
/**
* 解析结构化的报告草稿。