/** * LLM 客户端 — DeepSeek OpenAI 兼容接口 * * 设计要点: * - Key 从环境变量读取,永不写入代码或日志 * - 未配置 Key 时 isAvailable() 为 false,调用方返回 503,由 Java 端降级 * - 超时保护,避免长时间挂起 */ 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; maxTokens?: number; /** 思考强度;不传时不带 `reasoning_effort`,由供应商按自己的默认值处理 */ reasoningEffort?: ReasoningEffort; } export interface LlmConfig { apiUrl: string; apiKey: string; model: string; timeoutMs: number; } export function loadConfig(): LlmConfig { return { apiUrl: process.env.LLM_API_URL ?? "https://api.deepseek.com/v1/chat/completions", apiKey: process.env.LLM_API_KEY ?? "", model: process.env.LLM_MODEL ?? "deepseek-flash", timeoutMs: Number(process.env.LLM_TIMEOUT_MS ?? 120000), }; } export function isAvailable(config: LlmConfig): boolean { return config.apiKey.length > 0; } export class LlmError extends Error { constructor( message: string, public readonly statusCode: number, /** * 服务端给出的建议重试等待(毫秒)。 * * 来自 429/503 的 `Retry-After` 头;有值时退避重试应优先采用它, * 而不是用自己的指数退避——服务商限流时自己的退避往往偏短。 */ public readonly retryAfterMs?: number, /** * 这次失败的调用是否已经产生了 token 消耗。 * * 典型场景是上游返回 200 但内容为空:请求已经计费,只是没法用。 * 有值时调用方必须把它计入用量,否则这部分消耗会凭空消失。 */ public readonly usage?: TokenUsage, ) { super(message); this.name = "LlmError"; } } /** * 解析 `Retry-After` 头。 * * 规范允许秒数或 HTTP 日期两种形式,两种都支持;解析不出来时返回 undefined。 */ export function parseRetryAfter(value: string | null, now: number = Date.now()): number | undefined { if (!value) return undefined; const trimmed = value.trim(); if (trimmed.length === 0) return undefined; // 纯数字:秒 if (/^\d+$/.test(trimmed)) { return Number(trimmed) * 1000; } // HTTP 日期 const at = Date.parse(trimmed); if (Number.isNaN(at)) return undefined; return Math.max(0, at - now); } /** * 非流式调用,返回正文与上游上报的 token 用量。 */ export async function chat( config: LlmConfig, messages: ChatMessage[], options?: ChatOptions, ): Promise { if (!isAvailable(config)) { throw new LlmError("LLM API Key 未配置", 503); } const controller = new AbortController(); const timer = setTimeout(() => controller.abort(), config.timeoutMs); try { const response = await fetch(config.apiUrl, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${config.apiKey}`, }, body: JSON.stringify({ model: config.model, messages, temperature: options?.temperature ?? 0.3, max_tokens: options?.maxTokens ?? 2048, stream: false, // 思考强度交给调用方按内容长度决定;不传表示由供应商默认(DeepSeek 为 high) ...(options?.reasoningEffort ? { reasoning_effort: options.reasoningEffort } : {}), }), signal: controller.signal, }); if (!response.ok) { const body = await response.text().catch(() => ""); const retryAfterMs = parseRetryAfter(response.headers.get("retry-after")); // 保留上游真实状态码:重试策略靠它区分 429/5xx(可重试)与 4xx(不可重试) throw new LlmError( `LLM 请求失败 (${response.status}): ${body.slice(0, 200)}`, response.status, retryAfterMs, ); } const data = (await response.json()) as { 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, undefined, snapshot.usage); } 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") { throw new LlmError("LLM 请求超时", 504); } throw new LlmError(`LLM 请求异常: ${err instanceof Error ? err.message : String(err)}`, 502); } finally { clearTimeout(timer); } }