Idea: expose a count-based image offload budget (maxRequestImages) on llm-pi-ai routes

[Tony-ooo]

提议

为 llm-pi-ai provider profile 暴露一个按张数的图片淘汰预算 maxRequestImages，与既有的 maxRequestImageBytes 并列。

背景：字节预算锁不住张数

dsh-llm-pi-ai 目前只暴露按字节的图片卸载预算（maxRequestImageBytes，默认 20 MiB），它会在超限时把最旧的图片替换为文本占位符。方向是对的，但无法确定保留几张图。

原因是同等像素尺寸的图片，编码后字节数可能相差数倍。实测同一份 29 页 A4 扫描文档（953×1348，全部同尺寸）：

指标	实测值
单张 base64 长度	82,096 B ~ 447,016 B
波动倍数	5.45×

因此同一个字节阈值，保留张数会在很宽的范围里漂移。用真实的 offloadRequestImagesWithPolicy 跑这 29 页：

maxRequestImageBytes	保留张数（本文档）	全部稀疏页	全部密集页
4 MiB	13	51	9
3 MiB	10	38	7
1.25 MiB	5	15	2

要保证不超过某个张数上限，阈值必须按最小页面来定（16 × 82 KB ≈ 1.25 MiB），但那样遇到密集页只剩 2 张，实际不可用。

为什么张数维度是必需的

对本地/自托管后端，服务端往往有硬性的媒体张数上限，超限直接拒绝整条请求（而非降级）。真实案例（NInfer 在 OpenAI 兼容端点后）：

• 服务端 kMaximumMediaItems = 16，第 17 张直接 413
• 返回 413 media_budget_exceeded: request exceeds the 16-item media limit

于是在长对话里逐页读图（很常见：审阅扫描版论文/合同/报表）时，会话会在固定张数处永久卡死——每次请求都会重发历史全部图片，累计值只增不减，越线后该会话再也无法完成任何请求。

按张数淘汰能精确解决这个问题：保留最新 N 张，与图片内容/体积无关。

现状：底层已支持，只是没接出来

关键点是底层函数已经具备该能力：

• dsh-llm 的 offloadRequestImagesWithPolicy 已支持 maxImages + countQuantum（dsh-llm/lib/index.js 的 offloadedImagePrefixCount 同时处理张数与字节两个维度）
• dsh-llm-deepseek 已经接出来了：maxImagesPerRequest（默认 600）+ imageOffloadCountQuantum（默认 20）

唯独 llm-pi-ai 这条 pi-ai 兼容路由没有暴露。我已 grep 确认：maxImages 在 dsh-llm-pi-ai 中零命中，而 dsh-llm-deepseek 中有完整实现。

建议的改动

在 llm-pi-ai 的 provider profile 增加一个可选字段：

llm-pi-ai:
  providers:
    my-local-route:
      api: openai-completions
      baseURL: http://127.0.0.1:8080/v1
      maxRequestImages: 16        # 新增：保留最新 16 张；0 或缺省 = 关闭
      models:
        - id: my-model

实现上只需把 maxImages / countQuantum: 1 透传给 toPiContextWithImages 中已有的两处 offloadRequestImagesWithPolicy 调用（定价投影与发送投影都要传，保证两次选择一致），并像 maxRequestImageBytes 一样在 schema 和 resolveProfiles 中校验。语义上与 maxRequestImageBytes 取交集（两个预算同时生效），countQuantum: 1 可保证保留集合精确为最新 N 张。

参考实现（6 处改动，纯透传，无新逻辑）。已在 @deepseek-ai/dsh-llm-pi-ai 上验证可用：

@@ schema (lib/index.js ~L973)
 	requestImageMaxBytes: z.number().step(1).min(1).default(DEFAULT_REQUEST_IMAGE_MAX_BYTES),
+	maxRequestImages: z.number().step(1).min(0),
 	retryPolicy: RetryPolicySchema
 });

@@ resolveProfiles()（校验）
 	const requestImageMaxBytes = source.requestImageMaxBytes ?? 1048576;
 	if (!Number.isSafeInteger(requestImageMaxBytes) || requestImageMaxBytes <= 0) throw new Error(...);
+	// Optional image-COUNT budget: keep only the newest N images per request.
+	// 0 or absent disables the count bound and leaves bytes authoritative.
+	const maxRequestImages = source.maxRequestImages ?? 0;
+	if (!Number.isSafeInteger(maxRequestImages) || maxRequestImages < 0) throw new Error(...);

@@ resolveProfiles()（挂到 resolved profile）
 			requestImageMaxBytes,
+			maxRequestImages,
 			retryPolicy: resolveRetryPolicy(...),

@@ toPiContextWithImages()（构造 count policy）
-	const { attachments, resolveImageAccess, maxRequestImageBytes } = images;
+	const { attachments, resolveImageAccess, maxRequestImageBytes, maxRequestImages } = images;
+	const countPolicy = maxRequestImages === void 0 || maxRequestImages <= 0
+		? {} : { maxImages: maxRequestImages, countQuantum: 1 };

@@ 两处 offloadRequestImagesWithPolicy 调用（定价投影 + 发送投影）
 		...maxRequestImageBytes === void 0 ? {} : { maxBytes: maxRequestImageBytes },
+		...countPolicy,
 		byteQuantum: 1,

@@ PiAiAdapter（转发）
 					maxRequestImageBytes: profile.maxRequestImageBytes,
+					maxRequestImages: profile.maxRequestImages,
 					requestImagePolicy: {

要点：countQuantum: 1 保证保留集合精确为最新 N 张（并非按量子成批丢弃）；两处调用都传，保证定价投影与实际发送选择同一批图。我已在本地以 monkey-patch 方式验证：40 张历史被精确投影为最新 16 张；无论页面是 82 KB 还是 447 KB，保留张数恒为 16，服务端不再拒绝。

补充说明

• 该字段与 maxRequestImageBytes 并不冲突，两者可同时配置取交集；对不设张数上限的云端路由，保持缺省即可，行为完全不变。
• 若维护者认为张数维度不该进 pi-ai profile，另一种可选做法是在 dsh-llm 的公共 policy 层提供 maxImages 的统一入口，让各 adapter 共享同一套语义。

感谢维护者的工作。