# Contributor handoff — deepseek-ai/DeepSeek-V3

> Canonical page: https://codevetter.com/unpack/deepseek-v3/agent-handoff

# Contributor handoff — deepseek-ai/DeepSeek-V3

Scanned commit 9b4e9788e4a3a731f7567338ed15d3ec549ce03b (2025-08-28). Generated by codevetter codevetter 1.12.0 on 2026-09-22.

Small codebase, high blast radius: five Python files where every edit is near the numerics. Read README.md section 6 first for the intended workflow, then generate.py (orchestration), model.py (all architecture), kernel.py (Triton numerics), and convert.py (weight naming contract). Validation is manual — there are no tests — so the smoke path is `python model.py` (needs CUDA) or a short torchrun generate. Known traps: module globals set only in Transformer.__init__, the dim==7168 gate-bias hack, silent layer-61 drops in convert.py, assert-based validation, and the requirement to run everything from inside inference/ with per-rank shard naming.
- Read order for onboarding: README.md (workflow + ecosystem) -> inference/generate.py (CLI + distributed setup) -> inference/model.py (ModelArgs + all modules) -> inference/kernel.py (FP8 kernels) -> inference/convert.py (weight-name contract) -> README_WEIGHTS.md (checkpoint layout). — [README.md#L227-303](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/README.md#L227-L303) [inference/generate.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/generate.py) [inference/model.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/model.py) [inference/kernel.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/kernel.py) [inference/convert.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/convert.py) [README_WEIGHTS.md](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/README_WEIGHTS.md)
- Environment setup is exactly: cd inference && pip install -r requirements.txt (torch 2.4.1, triton 3.0.0, transformers 4.46.3, safetensors 0.4.5); Linux + Python 3.10 + CUDA only — Triton kernels and torch.set_default_device('cuda') mean no CPU/macOS path. — [inference/requirements.txt](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/requirements.txt) [README.md#L254-257](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/README.md#L254-L257) [inference/model.py#L803](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/model.py#L803)
- Canonical run commands: convert with 'python convert.py --hf-ckpt-path <hf> --save-path <out> --n-experts 256 --model-parallel 16', then generate with 'torchrun --nnodes N --nproc-per-node 8 generate.py --ckpt-path <out> --config configs/config_671B.json --interactive'. — [README.md#L283-303](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/README.md#L283-L303) [inference/convert.py#L88-96](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/convert.py#L88-L96) [inference/generate.py#L176-185](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/generate.py#L176-L185)
- Checkpoint shard naming is a strict contract between convert.py and generate.py: files must be named model{rank}-mp{world_size}.safetensors in --ckpt-path; a mismatch in world_size between conversion and torchrun silently loads nothing-compatible. — [inference/convert.py#L81](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/convert.py#L81) [inference/generate.py#L119](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/generate.py#L119)
- Always run scripts from inside inference/ — imports are bare ('from kernel import ...', 'from model import ...') with no package structure. — [inference/model.py#L10](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/model.py#L10) [inference/generate.py#L11](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/generate.py#L11) [inference/fp8_cast_bf16.py#L10](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/fp8_cast_bf16.py#L10)
- Trap: Gate.bias exists iff args.dim == 7168. When adding a config or changing dim, also check whether the checkpoint has e_score_correction_bias tensors, or load_model will fail on unexpected keys. — [inference/model.py#L563-564](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/model.py#L563-L564) [inference/convert.py#L61](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/convert.py#L61)
- Trap: world_size/rank globals and Linear.dtype are only assigned inside Transformer.__init__; never instantiate Block/MLA/Linear standalone expecting distributed or fp8 behavior. — [inference/model.py#L757-761](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/model.py#L757-L761) [inference/model.py#L13-17](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/model.py#L13-L17)
- Trap: convert.py drops all 'model.layers.61' tensors (MTP module). If asked to support MTP/speculative decoding, this skip plus the missing eh_proj/enorm/hnorm mapping entries are the first things to change. — [inference/convert.py#L53-54](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/convert.py#L53-L54) [inference/convert.py#L11-30](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/convert.py#L11-L30) [README_WEIGHTS.md#L41-48](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/README_WEIGHTS.md#L41-L48)
- Smoke-test procedure after edits: 'python model.py' should print a logits shape (requires CUDA); for a real check, convert a small config (config_16B.json) and run a 2-token generate — there is no automated test to run instead. — [inference/model.py#L801-808](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/model.py#L801-L808) [inference/configs/config_16B.json](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/configs/config_16B.json)
- Code conventions: every public class/function carries a docstring with Args/Returns; type hints use typing.Literal for mode switches; distributed code checks 'if world_size > 1' before every collective; keep new code consistent. — [inference/model.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/model.py) [inference/kernel.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/kernel.py) [inference/generate.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/generate.py)
- Safe edit boundaries: kernel.py Triton code and Gate routing math are numerics-critical and untested — changes there need manual numerical comparison; generate.py CLI plumbing and convert.py key renames are lower-risk. (inferred) — [inference/kernel.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/kernel.py) [inference/model.py#L535-598](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/model.py#L535-L598) [inference/generate.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/generate.py) [inference/convert.py](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/convert.py)
- Do not commit model weights or generated shards — nothing in .gitignore excludes *.safetensors or checkpoint dirs, so a careless 'git add -A' can stage hundreds of GB. — [.gitignore](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/.gitignore)
- Do not change the pinned repo state expecting upstream compatibility: HF Transformers is explicitly unsupported, and the demo expects weights already converted to its shard format. — [README.md#L249-250](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/README.md#L249-L250) [inference/generate.py#L119](https://github.com/deepseek-ai/DeepSeek-V3/blob/9b4e9788e4a3a731f7567338ed15d3ec549ce03b/inference/generate.py#L119)

Every claim links to its cited files at the pinned commit. Citations identify source evidence; they do not establish runtime correctness. Independent CodeVetter scan — not reviewed by upstream maintainers.

## Public product links

- [CodeVetter](https://codevetter.com/)
- [Download](https://codevetter.com/download)
- [Documentation](https://codevetter.com/docs/)
- [Source](https://github.com/Codevetter/codevetter)