Give analysis three workers, and say why cpus alone was not enough

[jeffcrouse]

The re-analysis from #258 was running at 31.7 s/track, ~230 hours. Two changes take it well below that, and the first cost nothing at all.

The CPU limit was already right in this file, and inert on the machine

docker-compose.prod.yml has said cpus: '6.0' since issue #13. The running container had 2.0. The comment directly above the limit already explains why:

deploy-dev.sh does docker cp + docker restart, which preserves the container's existing HostConfig — it will NOT apply a change made here.

So the fix needed no restart and no code:

docker update --cpus=6 familiar-api

31.7 s/track → 15.7 s/track. Measured over 600 s in both cases. ~230 h → ~112 h.

That is this project's recurring shape again — a change correct in the repo and absent from the running system — except here the file had already documented its own failure mode and nobody had run the one command.

Workers need a recreate, which has a trap

MAX_ANALYSIS_WORKERS is read from the environment at process start, so docker update cannot set it. Recreating the container discards whatever deploy-dev copied in — verified rather than assumed:

	chunked-mean markers	EMBEDDING_VERSION
running container	2	7
ghcr.io/...:latest image	0	6

After the recreate the container was serving middle-ten-second embeddings again until make deploy-dev was re-run. The sequence is now documented beside the setting.

Sizing

One worker leaves most of a six-core allowance idle — a track is one process, and max_tasks_per_child=1 means it does not even amortise its own interpreter start.

Memory goes 6G → 10G because each worker holds a CLAP model. The old comment claimed "~4GB peak"; measured reality was 1.57 G total with one worker running, so this is headroom rather than a requirement.

Applied to the NAS

Live now: 6 CPUs, 10 G, 3 workers, chunked-mean code restored and verified. Three-worker throughput is being measured.

Note: the NAS copy of this file had drifted from the repo — still cpus: '2.0', music mounted rw rather than ro, no mixtapes volume, plus ANTHROPIC_API_KEY/SPOTIFY_* this repo dropped with ADR-0048. I patched it surgically rather than overwriting, since reconciling that drift is a separate change and this one was made mid-re-analysis. Worth doing deliberately later.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Emjrwedq7W1scadHdgiLfs

[jeffcrouse]

Measured: three workers, and the scaling is worse than expected

configuration	rate	remaining
1 worker, 2 CPUs	31.7 s/track	~230 h
1 worker, 6 CPUs	15.7 s/track	~112 h
3 workers, 6 CPUs	11.3 s/track	~80 h

All three measured over 600 s against count(*) where embedding_version >= 7.

Three workers bought 1.4×, not 3× — 46% efficiency. And it is not CPU or memory that stops it:

cpu  296% – 328%   (of 600% allowed)
mem  1.8 – 2.3 GiB (of 10 GiB)

Both have plenty of headroom, so the wall is disk I/O. That matches the per-track breakdown taken earlier, where one cold decode took 19 s against 1.4–1.8 s warm: three processes doing random reads off the array contend with each other, and with music streaming.

So this stops at 3. More workers would mostly thrash and would compete with playback on the machine that serves it. If this needs to go faster later, the lever is the storage path — not more processes.

The 10 G memory limit turns out to be unnecessary. Peak was 2.3 GiB with three workers, against an old comment claiming "~4GB peak" for one. It is harmless headroom, but nobody should read it as a requirement.

Net effect of both changes: ~230 h → ~80 h, and the first half of that came from a command the file had already documented.

[jeffcrouse]

Superseded by the PR above — this branch predates #262 and merging it would revert NVIDIA_DRIVER_CAPABILITIES=compute,utility, which is what lets libcuda.so reach the container. Losing it returns the deployment to CPU silently.

Everything else here (cpus: '6.0', memory: 10G) already landed via #262. The replacement carries only the missing MAX_ANALYSIS_WORKERS, on top of current main.

[jeffcrouse]

Closing so it cannot be merged by accident: this branch predates #262 and merging it would revert NVIDIA_DRIVER_CAPABILITIES=compute,utility, silently returning the deployment to CPU.

Replaced by #268, which carries the one thing still missing (MAX_ANALYSIS_WORKERS) on top of current main.

A closed PR only protects against this branch, so #268 also adds a test asserting the compose settings that are load-bearing and invisible when removed.