Repeated parsing of the DeepSeek Files index slows image-heavy sessions

[xuhao1]

Summary

While profiling long sessions with hundreds of retained images, I found that resolving images which were already uploaded still spent a surprising amount of time in the local upload index.

DeepSeekUploadIndex.get() reads and parses the entire files-v3.json file, validates all its records, and scans the records for each lookup. Resolving 500 retained image mappings therefore reads and parses the same index roughly 500 times before sending the next model request. Adding one new image between requests keeps this overhead on the request path.

I'm posting here because the contribution guide directs bug reports to Discussions and the repository currently has Issues and external PRs disabled. I have prepared a small implementation in a fork for review; it does not change model settings or prompts.

Reproduction

The contribution includes a keyless benchmark at packages/llm/llm-deepseek/benchmarks/upload-index.ts. It uses synthetic upload records, so it needs no images, credentials, GPU, or API calls.

From the contribution checkout, after pnpm install --frozen-lockfile:

# Current implementation
pnpm exec tsx --tsconfig tsconfig.base.json packages/llm/llm-deepseek/benchmarks/upload-index.ts

# Same benchmark against the unmodified upstream implementation
git show 5badb15009ae1756c3afe0ae0cef1faafc290ccc:packages/llm/llm-deepseek/src/upload-index.ts > packages/llm/llm-deepseek/src/upload-index.baseline.ts
pnpm exec tsx --tsconfig tsconfig.base.json packages/llm/llm-deepseek/benchmarks/upload-index.ts packages/llm/llm-deepseek/src/upload-index.baseline.ts
rm packages/llm/llm-deepseek/src/upload-index.baseline.ts

Each batch commits one new mapping, then looks up every mapping and checks the returned file IDs. There are two warmup batches followed by five measured batches. Timings include the first lookup after each commit, but exclude the commit itself.

Current behavior

Here are the results from the same machine, using the same benchmark for both versions:

Initial mappings	Lookups per measured batch	Upstream median	Patched median
100	103–107	31.58 ms	4.04 ms
500	503–507	556.08 ms	17.44 ms

These are local lookup timings, not end-to-end model latency. The 500-record case took about 97% less lookup time. I am not claiming a provider token-cache or billing improvement from this patch; it does not change the request sent to the model.

Expected behavior

An unchanged index should be parsed once and reused for subsequent image lookups. A new upload or another process changing the index must still become visible, and expiry checks must still use the current time and refresh margin.

Environment

• DSH / @deepseek-ai/dsh-llm-deepseek: 0.2.1-alpha.1.
• Upstream base: 5badb15009ae1756c3afe0ae0cef1faafc290ccc.
• Ubuntu 22.04.5 LTS, Linux x64, kernel 5.15.0-125-generic.
• Node.js 24.15.0, pnpm 11.7.0; AMD EPYC 9T24 CPU.
• Temporary index files on a local filesystem. Synthetic mappings exercise the native DeepSeek Files index; no model or provider is called by the benchmark.

Proposed fix

Keep one parsed document and a lookup map per index instance. Check the file identity, size, and nanosecond modification/change times before reuse, and check again before retaining a newly read document. Invalidate the cache before and after local writes so an overlapping read cannot leave an older generation installed after the write finishes.

The patch retains the existing parser, locks, atomic writes, expiry rules, exact-generation removal, and v3 file format. Returned records are copied so a caller cannot modify the cached records. Only index files up to 8 MiB are eligible for retained parsing; larger files keep the uncached behavior. That ceiling measures serialized file size, not JavaScript heap usage.

The focused index and Files tests pass (73 tests), with 100% statement, branch, function and line coverage for the changed index module. Running the two new read-reuse regressions against the original implementation fails as expected: they observe six and three reads where the patched implementation reads once.

I would be happy to adjust the approach if there is a preferred way to cache this index upstream.

Implementation: xuhao1@adc30f3

Review PR (in my fork; not an upstream PR): xuhao1#1

[PerryLink]

这是一个读放大问题——而且你的量测方式本身值得肯定

1. 你指出的形态是清楚的

DeepSeekUploadIndex.get() 每次查找都要：读整个 files-v3.json、校验全部记录、再线性扫描找那一条。⇒ 在"同一批图片被反复引用"的长会话里（你说解析 500 次已上传的图片），这就变成每次一张图 = 一次全文件解析 + 全表扫描 ⇒ 时间随"索引大小 × 查找次数"增长。

建议在报告里把这个复杂度写出来（例如"单次查找 O(记录数)，而查找次数随会话长度线性增长 ⇒ 总体 O(n²)"）。这类报告最容易卡在"感觉慢"，写出阶数就变成可讨论的性能缺陷。

2. 修法方向（按收益排序）

1. 进程内缓存：解析结果在内存中保留一份，并按 mtime/size 失效 —— 单这一步就能把"每次读+解析"降为"每次查内存"；
2. 索引化：把记录做成 Map<key, record>，把线性扫描降为常数查找；
3. 校验前移：全量校验只在首次读取时做一次，而不是每次查找都做。

建议把第 1 条写成最低要求（改动最小、收益最大），第 2、3 条作为后续。

3. 请补三样（把"慢"变成可复现的数字）

1. 时间量测：500 次解析里，读文件 / 解析 JSON / 校验 / 扫描各占多少（你已经在 profiling，把这几项分开即可——分开之后修哪一处就有了依据）；
2. 索引规模：那台机器上 files-v3.json 的记录数与文件大小；
3. 版本：你未写版本。⚠️ 当前最新是 0.2.1-alpha.1（latest/next = 0.2.0-rc.2）——请补基线，packages/llm 在 0.1.7-rc.2 → 0.2.1-alpha.1 之间有 70 个提交。

4. 一条相关线索

同日另有一条关于图片处理的报告（#8793：read_image 只传动画 GIF 的首帧且无提示）。两条不同因（一条是性能、一条是行为）——建议只互相引用，不要合并：它们该由不同人修。

5. 关于可复现性

你这条天然可复现（同一索引、反复解析同一批图片即可）。建议写成一个可跑的判据，例如："在含 N 条记录的索引上连续 get() M 次，记录总耗时"——把 N、M 与耗时一起给出，任何人都能在自己的机器上对照。这比"我很慢"强得多。

一条边界

我没有读 upload-index.ts 的实现（上面的修法方向来自你对行为的描述）。若你把第 3 节的量测补齐，我可以对着 packages/llm/llm-deepseek/src/upload-index.ts 再核一次"哪一步最贵"。

[xuhao1]

谢谢你的建议，尤其是把读取、解析、校验和查找分开量测这一点。我补了分项诊断，也把复现基准和回归测试作了两处小改进，已更新到 fork PR #1。

为方便核对，基线是 DSH / @deepseek-ai/dsh-llm-deepseek 0.2.1-alpha.1，上游 commit 5badb15009ae1756c3afe0ae0cef1faafc290ccc。按有界记录大小计，N 条索引记录、M 次查询的原路径工作量是 O(NM)；当 M 随 N 同阶增长时，单批次为 O(N²)。

更新后的无 API 基准会逐批输出记录数、索引文件字节数和耗时。今天在同一台 Linux / EPYC 9T24、Node 24.15.0 环境复跑，仍是 2 次预热、5 次测量，每批先提交一个新映射再查询全部映射，提交时间不计入，返回的 file ID 全部核验：

初始记录数	每个测量批次的记录数 / 查询次数	索引文件大小	原版中位耗时	补丁中位耗时
100	103–107	41,546–43,162 bytes	35.08 ms	3.52 ms
500	503–507	203,146–204,762 bytes	567.50 ms	21.49 ms

另一次独立的基线插桩诊断中，500 条初始记录场景的五个测量批次累计耗时占比为：readFile(utf8) 38.12%、JSON.parse 19.39%、完整校验（含重复键检查）41.84%、find 0.40%。这支持你对读放大的判断：这里主要花在重复读取、解析和校验。分项数据包含插桩开销；读取计时还包含 UTF-8 解码和异步调度，未清空 OS page cache，因此不是物理磁盘耗时。这些都是合成索引的本地测量，不能外推成模型端到端或费用收益。

实现上，现有补丁已把解析结果复用、Map 查询和按新索引代重新全量校验放在一起；每次查询仍检查文件状态和当前过期条件。失效判断保留 dev/ino/size/mtimeNs/ctimeNs，用于覆盖同尺寸、恢复修改时间的原子替换。

沿着这个边界回查时，我发现原测试用 Date 恢复 mtime 会丢失亚毫秒精度，可能让一个仅比较 size/mtime 的弱实现也通过。现在测试将两代文件设置为相同整数秒时间，并明确断言 size、mtimeNs 完全相同且 inode 不同，再检查返回新 file ID。37 项索引测试通过；临时将签名弱化为仅 size + mtimeNs 后，该测试按预期失败。

新增提交：3f37180。PR 中也补了测量方法和验证说明。谢谢你指出这些值得补充的证据。

[argszero]

Source-verified on 5badb15009 (the base you used), plus a runtime probe and the cost breakdown the thread asked for. Reading only — I did not exercise a live Files request.

1. The chain: one full read and one full validation per image, per HTTP attempt

adapter.ts:95 → prepareFileIds() (images.ts:99) walks every image reference of every message and awaits RequestFiles.resolve() (request-files.ts:116) → DeepSeekFileStore.ensureUploaded() → ensureUploadedOnce() (file-store.ts:188) → this.index.get(...) (file-store.ts:200). release() (file-store.ts:266) also goes through get() (:273).

get() (upload-index.ts:149) calls this.load() (:123) = readFile + parseIndex (JSON.parse + per-record regex validation + duplicate-set) + a linear .find. So each image pays one read and one whole-file validation. The inflight map only dedups while an upload is still unsettled, and its entry is removed as soon as it settles, so a repeated variant later in the same request can look the index up again.

2. Where the time actually goes

Published @deepseek-ai/dsh-llm-deepseek@0.2.1-alpha.1, 500 records / 201 KB index, Node 26.5.0, macOS arm64 (APFS), 500 sequential lookups after warmup:

step	total	per call	share
get() × 500	228.2 ms	0.456 ms	100%
readFile() × 500	32.0 ms	0.064 ms	14%
JSON.parse() × 500	73.3 ms	0.147 ms	32%
validate + scan (by difference)	122.9 ms	0.246 ms	54%

Parse + per-record validation ≈ 86%; the file read is the minority. A cache that only avoids the read (the OS page cache already absorbs much of it) recovers little — the parse/validate result is what has to be reused. Validation is parseRecord's ~10 regex tests per record, so this is also the part that stays expensive as the file grows.

3. Read amplification is exactly 1:1, deterministically

50 get() calls → 50 load() invocations, counted by wrapping the prototype. Delete the index file and the very next get() returns undefined — nothing is retained between calls. Your "500 images ⇒ ~500 reads and parses" is the right shape.

4. Your identity check has a stronger form available

Every local write goes through writeFileAtomic (@deepseek-ai/dsh-atomic-write): a random-suffix sibling plus rename() over the target. Measured, two consecutive commit()s produce a different ino (340187635 → 340187637) and a different size, and the rename is what makes the write visible at all. So ino is a free, very robust generation marker — it changes on every write, including a write landing in the same millisecond as the read before it, where mtime alone is coarser than this write protocol.

5. Why this is a plugin-shaped gap (and its boundary)

There is no cordis service to shadow here: registerDeepSeekProvider() (host.ts:23) never passes resolveFiles, so DeepSeekAdapter's constructor does new DeepSeekFileStore() (adapter.ts:29) with new DeepSeekUploadIndex() inside it — a private field of a private field of the adapter. The only seam a third-party package has is the exported class: DeepSeekUploadIndex.prototype.load / .get survive bundling in the shipped lib/index.js, are writable, and a probe confirms that wrapping load is what get() then calls (the methods are non-enumerable class methods; restoring the original is clean). Honest boundary: such a patch silently does nothing if a profile happens to load a second copy of the package — a known failure mode of this repo's profiles — so a wrapper has to verify itself against the live instance (ctx.llm → registration → adapter → .files → .index) and report "not applied" rather than claim success.

6. Two notes on your patch

• Replacing only load()'s read+parse is enough: the parser, locks, expiry rule and v3 format stay exactly as they are, so the divergence surface is the smallest possible while still buying the 86%.
• Since validation dominates, "validate once per read" is doing most of the work alongside "parse once" — worth saying explicitly in the description, because it is the half that does not get cheaper as the file grows.

Boundary: static reading of 5badb15 plus standalone probes against the published bundle; the absolute ms are this machine, so treat the shares as the transferable part.

[argszero]

A plugin for this gap: @argszero/dsh-upload-index-cache

The analysis in this thread already says what the change should be — memoize the parse, leave everything else alone — so this is that change packaged rather than another proposal. I built and published it.

• npm: https://www.npmjs.com/package/@argszero/dsh-upload-index-cache
• source: https://github.com/argszero/dsh-upload-index-cache

Mounting it, through the bundle-patch convention (a direct ctx.plugin(cache, { ... }) works the same way and takes the same config):

- insert:
    - id: upload-index-cache
      name: '@argszero/dsh-upload-index-cache'

What it does. It memoizes load() — the readFile + JSON.parse + per-record validation — and re-reads only when the file's identity (ino, size, mtimeMs) changes. The inode is the load-bearing field: writeFileAtomic renames a random-suffix sibling over the target, so every local write changes it, and a key of mtimeMs alone cannot promise to see a write that lands inside the same millisecond as a preceding read. A lookup stats the file, and stats it again before retaining a freshly parsed document, so a read that raced a write is served (it is a consistent snapshot of some generation) but is not retained — an older generation can never end up installed after a newer write finished.

It does not touch the parser, the expiry rule, the lock, the atomic write, the v3 format or get()'s linear scan. The saving is therefore bounded by what memoizing load() can honestly claim: with the numbers from my previous comment, the 99.3% (read + parse + validate) minus the ~2.3% a stat costs. The 0.7% .find stays, and so does the parse on the first lookup of a request.

Why observe is the mode to start with. How often the file is read is a property of the deployment, not of the code: a session whose images are all already uploaded pays the full parse on every request, while a program that has never uploaded anything pays almost nothing. mode: 'observe' installs the same discovery and the same counters and patches nothing, so the amplification is measured before it is cached. ctx.get('uploadIndexCache').snapshot() reports lookups/hits/misses/bypassed and, separately, what it could not cover.

The seam, since DeepSeekUploadIndex is not a cordis service. The host builds the adapter with no resolveFiles, so the index is a private field of a private field. The plugin takes live instances from the public llm.registerAdapter call and, best-effort, from the registry's own adapter map (which is also the only way an adapter registered before mount is reached), and patches the instance — never a prototype, because a prototype belongs to whichever copy of the package happened to be imported, and patching the wrong copy is a failure this repository has already shipped twice. An index no registered adapter owns is invisible to it; the snapshot states that instead of implying full coverage.

Verification. 52 tests, including a control arm that runs the same sequence with the plugin absent and watches the second lookup fail with EACCES — a result only reachable if the first lookup really was retained. 22 mutation arms (one rule deleted at a time, e.g. the inode dropped from the identity key, observe installing the patch anyway) are all caught by the suite. Both claimed lines — 0.1.7-rc.2 and 0.2.0-rc.2 — were probed with every harness package pinned to the line (24 packages each, versions read back after install). Zero runtime dependencies: every harness import is type-only and erased, so lib/ reaches for nothing but node: builtins and its own modules.

Peer range: @deepseek-ai/dsh-llm \>=0.1.7-rc.2 <0.2.0 || >=0.2.0-rc.2 <0.2.1`. @deepseek-ai/dsh-llm-deepseek` is deliberately not a dependency — the plugin never imports the package it patches, because that import is exactly how a second copy gets materialized.

One real difference, stated rather than left to be discovered: callers of the memoized load() share one parsed object, where the unpatched method hands each caller a fresh parse. Nothing in the deepseek package mutates what load() returns — commit(), remove() and clear() build a new records array and assign it to a local — so it is unobservable today; it is the price of not paying the copy, and the README says so under "Honest boundaries".

[xuhao1]

Gentle ping @CreatixChu, since you recently worked on the DeepSeek Files upload index. When you have a moment, would a small parsed-index cache be something the team would consider in the native adapter, or would you prefer this to remain a community plugin for now?

The report now includes a keyless reproduction, per-stage timings, and an independently reproduced diagnosis from argszero above. Thank you to argszero for investigating and providing a plugin option as well.

Our reference implementation is in fork PR #1. In a local synthetic benchmark with roughly 500 retained mappings, the lookup batch went from 567.50 ms to 21.49 ms; this is local index time, not an end-to-end model or billing claim. The latest follow-up adds exact index byte counts and strengthens the same-size/restored-mtime regression. All 37 focused index tests, documentation checks, lint, and the normal pre-push typecheck passed.

We understand that external PRs are not currently accepted; the fork is just a reviewable reference if useful. Happy to adjust the scope to the team's preferred approach. No urgency, and thanks for your time.