From fd1193a66fd14d34108dd7c0e01da3a99b6d50c9 Mon Sep 17 00:00:00 2001 From: cat-shark <1716967236@qq.com> Date: Sat, 10 Oct 2026 17:53:41 +0800 Subject: [PATCH] =?UTF-8?q?perf:=20LLM=20=E6=8C=89=20prompt=20=E9=95=BF?= =?UTF-8?q?=E5=BA=A6=E8=87=AA=E9=80=82=E5=BA=94=E6=80=9D=E8=80=83=E5=BC=BA?= =?UTF-8?q?=E5=BA=A6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 12 ++++++ AGENTS.md | 12 ++++++ roles/task-queue.md | 5 ++- src/llm/client.test.ts | 66 ++++++++++++++++++++++++++++++ src/llm/client.ts | 14 ++++++- src/llm/thinking.test.ts | 87 ++++++++++++++++++++++++++++++++++++++++ src/llm/thinking.ts | 74 ++++++++++++++++++++++++++++++++++ src/task-queue.test.ts | 34 +++++++++++++++- src/task-queue.ts | 23 +++++++++-- 9 files changed, 321 insertions(+), 6 deletions(-) create mode 100644 src/llm/client.test.ts create mode 100644 src/llm/thinking.test.ts create mode 100644 src/llm/thinking.ts diff --git a/.env.example b/.env.example index acb649e..5be7160 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 5ce3e29..19f30ae 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 # 单任务总尝试次数(含首次) diff --git a/roles/task-queue.md b/roles/task-queue.md index 7acbdcf..7ec5ba8 100644 --- a/roles/task-queue.md +++ b/roles/task-queue.md @@ -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 条请求/响应。 diff --git a/src/llm/client.test.ts b/src/llm/client.test.ts new file mode 100644 index 0000000..232f325 --- /dev/null +++ b/src/llm/client.test.ts @@ -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): Record { + const init = fetchMock.mock.calls[0][1] as RequestInit; + return JSON.parse(String(init.body)) as Record; +} + +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"); + }); +}); diff --git a/src/llm/client.ts b/src/llm/client.ts index 1501fe3..9710746 100644 --- a/src/llm/client.ts +++ b/src/llm/client.ts @@ -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 { 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, }); diff --git a/src/llm/thinking.test.ts b/src/llm/thinking.test.ts new file mode 100644 index 0000000..74c0626 --- /dev/null +++ b/src/llm/thinking.test.ts @@ -0,0 +1,87 @@ +import { describe, expect, it } from "vitest"; +import { + loadThinkingConfig, + promptLength, + reasoningEffortFor, + type ThinkingConfig, +} from "./thinking.js"; + +const config = (overrides: Partial = {}): 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"); + }); +}); diff --git a/src/llm/thinking.ts b/src/llm/thinking.ts new file mode 100644 index 0000000..b9a1a16 --- /dev/null +++ b/src/llm/thinking.ts @@ -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"; +} diff --git a/src/task-queue.test.ts b/src/task-queue.test.ts index 0bcb95b..2b9542a 100644 --- a/src/task-queue.test.ts +++ b/src/task-queue.test.ts @@ -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" }] }); diff --git a/src/task-queue.ts b/src/task-queue.ts index b552ccd..46c056a 100644 --- a/src/task-queue.ts +++ b/src/task-queue.ts @@ -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) }; +} + /** 把模型原文转成结构化结果 */ /** * 解析结构化的报告草稿。