Repository navigation
Commit bba7552
authored
[docs] Refresh README, runtime APIs, and success stories (pytorch#22620)
> Updated to `be40b66f45` after merging upstream `main` at `f5e136973d`.
The review fixes are pushed, the PR diff remains documentation-only, and
fresh CI is in progress.
### Summary
Refreshes the README, documentation homepage, examples index, and
success
stories around the current ExecuTorch feature set. The new structure
leads with
current workloads, a runnable export-to-runtime path, language APIs,
hardware
backends, and evidence-backed production use.
The model section is intentionally representative rather than
exhaustive. It
shows credible text, multimodal, speech, vision, and embedded workflows,
then
explains how developers can adapt those patterns to another PyTorch
model and
validate export, operator, backend, numerical, memory, and performance
coverage
for their own target.
The getting-started path now continues through serialization, Python
runtime
loading, execution, and an eager-output assertion. Export guidance
distinguishes
standard PyTorch export, the experimental Transformers ExecuTorch
exporter,
Optimum ExecuTorch, and native `export_llm` workflows. Runtime
documentation maps
general `.pte` execution and high-level generation APIs across C++,
Python,
Android, Apple platforms, and WebAssembly.
Production claims cite primary sources and are separated from published
case
studies, integrations, technical showcases, and community prototypes.
Additional ecosystem stories cover NVIDIA FLARE, Unsloth, and Digica.
NoemaAI
appears near the bottom as a community app explicitly marked as not yet
vetted
by the ExecuTorch team, not as a production deployment.
Follow-up review corrections align both Android build guides with the
helper's
current `ANDROID_SDK` behavior, make nightly installation commands
upgrade
existing packages, fix the installed LLM exporter module path, and
distinguish
streaming Voxtral Realtime from offline Parakeet speech recognition.
This PR intentionally contains documentation content only. Runtime,
build,
package-manifest, and repository-configuration findings from validation
are
tracked in follow-up issues below. The standalone `website/` is
unchanged from
`origin/main`; its visual redesign will be handled separately.
This includes release-facing documentation: `README-wheel.md` is the
published
PyPI description, removes the old beta notice, and advertises Windows
x86-64
wheels. API, backend, and model availability/maturity labels and the
Vulkan
quantization description are also part of this review. These are
documentation
claims to review against the lifecycle policy, source, and published
artifacts;
no packaging code or API lifecycle implementation is changed.
For review, start with `README.md`, then `docs/source/index.md`,
`docs/source/pathway-quickstart.md`, and
`docs/source/success-stories.md`. The
platform details are in the Android, iOS, build-from-source, Vulkan,
MLX, LLM,
and runtime API pages.
Authored with Codex (OpenAI).
### Review follow-up
`10c02b87b9` corrects the Android release/snapshot paths and legacy
download
links, documents the separate QNN runtime dependency, and restores the
`viable/strict` source-build pin used by the release script. It fixes
all seven
checkout-only LLM exporter commands and corrects metadata names and
Hydra JSON
quoting. It separates YAML from shell commands, and documents Python
custom/quantized operator
registration and the currently ignored grammar fields. It also corrects
artifact
trust guidance, Apple lifecycle wording, the Gradle variable, and the
MLX
configuration explanation, and restores the LoRA/audio-generation
showcase links.
`d6700c5538` keeps the language API table on the API page, fixes the
separate
text/multimodal runner links, and points README documentation links at
rendered
pages. The README retains its backend table, restores the desktop guide
link,
and scopes CUDA wheel guidance to Linux. Read the instruction-fix commit
first,
then this navigation cleanup. Wider cross-page consolidation remains
separate.
Both commits modify Markdown only; the full PR still changes 32 Markdown
files.
### Validation
#### After upstream synchronization
Merged current `main` (`f5e136973d`) in `be40b66f45`, incorporating the
existing
MLX batched-runner and LoRA shared-cache cleanup fixes from pytorch#22627 and
pytorch#22632.
All 13 review-fix files were preserved unchanged; the C++ guide also
retains
main's clarification that `kernels_torchao` supports Linux and macOS on
aarch64.
GitHub and local comparison against the new base both show 32 Markdown
files,
with no website, runtime implementation, build-system, or configuration
changes
in the PR diff.
The configured pre-commit hook passed before the merge. After the merge,
lintrunner, URL/xref/file-size lints against `origin/main`, diff checks,
and
rendered-HTML/anchor checks passed. URL lint checked 166 links without
warnings.
`make -C docs html-noplot` completed with exit 0, but logged 131
warnings and
one CRITICAL missing-include diagnostic in `llm/llama-demo-ios.md`. The
same
missing iOS demo README include exists on `main` and in the pre-merge
log; it
is not changed by this PR. Tutorial execution was disabled, and this is
not a
clean Sphinx build. The earlier end-to-end checks below were not rerun
as part
of this synchronization, and local validation does not establish full CI
success.
#### Review follow-up validation
The configured pre-commit hook ran successfully for both local commits
without
bypassing it. Lintrunner, URL/xref/file-size lints over the full PR
range, and diff
checks passed at `d6700c5538`. No runtime, workflow, or build-system
changes are
included in these commits.
Before committing, the exact README and quickstart Add/XNNPACK blocks
ran outside
the checkout with the published macOS arm64
`executorch-1.6.0.dev20260915` wheel;
both exported, serialized, loaded, executed, compared against eager, and
printed
`Output: tensor([2.])`. Six tiny random-weight Llama exports passed,
including
KV-cache/SDPA, quantization, XNNPACK, and ETRecord; basic Runtime
execution and
optimized/delegated TextLLMRunner generation also passed. The six YAML
snippets,
corrected Hydra metadata command, and operator-registration snippet were
checked;
nine runner Python blocks compiled, and the generated ETRecord parsed.
The initial optimized-runner missing-operator errors were resolved by
explicitly
registering the custom and quantized kernels. The wheel ships them; this
is now
documented, not reported as a missing-artifact runtime defect. The test
venv
reused existing dependencies via `--system-site-packages`, so this is
not a
pristine dependency-installation test. Tiny random models and a
synthetic
tokenizer validate the path, not pretrained-model quality or
performance.
Seven Android AAR/checksum pairs downloaded and verified: 1.4.1
XNNPACK/QNN/Vulkan,
the 2026-09-14 XNNPACK snapshot, and the three restored legacy releases.
Both
documented download blocks ran verbatim; artifact inspection confirmed
the
separate Qualcomm runtime requirement. No new Android build, Gradle
sync, or
physical-device execution was performed in this follow-up.
Rendered README destinations and actual section anchors were checked,
including
19 live documentation URLs and all 45 README main-docs URLs against
local HTML.
`make -C docs html-noplot` succeeded with 138 reported diagnostics on
the first rebuild and
126 on the final incremental build; tutorial execution was disabled.
This is
not a warning-free build or a claim that every documented snippet ran
end to end.
#### Earlier validation
For the success-stories follow-up `c0c34676f7`, the configured
pre-commit hook,
URL/xref/file-size lints, and diff checks passed. All six new source
links return
HTTP 200. `make -C docs html-noplot` passed with 126 reported
diagnostics elsewhere in the
docs and none for `success-stories.md`; tutorial execution was disabled.
These
checks validate the documentation and sources, not the external vendor
workflows.
Checks rerun for review follow-up `b3f1cfb1d2`:
```text
.githooks/pre-commit
lintrunner -m 01cc075
scripts/lint_urls.sh 01cc075 HEAD
scripts/lint_xrefs.sh 01cc075 HEAD
bash scripts/lint_file_size.sh 01cc075 HEAD
make -C docs html-noplot
git diff --check 01cc075...HEAD
```
All passed. The configured pre-commit hook also ran during `git commit`,
without bypassing it. Sphinx completed with 224 reported diagnostics;
tutorial execution
was disabled for this documentation-only follow-up. A full
`make -C docs clean html` was run during the earlier validation.
Executed end to end on Apple silicon/macOS while developing the
documentation:
- Stable 1.4.1 and nightly 1.5.dev wheel installs; the README
Add/XNNPACK flow;
MobileNet V2 export and runtime comparison; dynamic-shape export; and
separate
`.pte`/`.ptd` loading.
- The nightly C++ wheel walkthrough through export, CMake configuration,
compilation, linking, loading, and execution, including the XNNPACK
component.
- Core ML export and execution with eager comparison. MLX MobileNet
export
produced one delegate, and 82 MLX export/unit tests passed. MLX GPU
execution
was unavailable because this host blocks the Metal JIT cache.
- Portable, float XNNPACK, and quantized XNNPACK MobileNet; Wav2Letter,
MLPerf
Tiny DS-CNN, Silero VAD, Whisper preprocessing, and scaled YOLO26 export
and
runtime comparisons.
- Native tiny-Llama export plus Python and C++ generation; 13 Python LLM
binding
tests and 117 runnable C++ runner tests. Transformers exporters were
exercised
with tiny BERT and Llama models through `.pte` execution.
- Fresh `optimum-executorch==1.1.0` basic and optimized SmolLM2-135M
exports,
reload, and generation; plus tiny XNNPACK and portable Llama paths.
- Published stable and nightly Apple xcframeworks through Swift and
Objective-C
execution, 130 Swift tests, simulator builds for both channels, a
nightly iOS
device build, and compile validation of `TextRunner`.
- The documented Android 1.4.1 XNNPACK AAR download and SHA-256
verification;
Maven/release artifact contents, ABIs, and Java/Kotlin API symbols;
ModuleAdd
export and host execution.
- Vulkan MobileNet, dynamic-shape, bundled-program, FP16 Inception V3,
4-bit,
and 8-bit exports, plus 119 non-runtime Vulkan tests.
Large Llama, Qwen, Gemma, Parakeet, and Voxtral weights were not
downloaded in
full; their CLI/configuration surfaces were checked and smaller models
exercised
the same exporters and runners. CUDA, QNN, MediaTek, Samsung, Arm
accelerator,
and physical-device execution require hardware or toolchains unavailable
on this
host. Repository CI remains the cross-platform gate.
### CI status
Fresh checks are attached to the published head `be40b66f45`, not
inherited from
the previous head.
[Lint](https://github.com/pytorch/executorch/actions/runs/35006697462),
[documentation
build](https://github.com/pytorch/executorch/actions/runs/35006697815),
and
[MLX](https://github.com/pytorch/executorch/actions/runs/35006698009),
together
with the [pull
tests](https://github.com/pytorch/executorch/actions/runs/35006698583)
including LoRA and QNN, are running or queued. Results were pending at
publication;
this is not a claim that CI is fully green.
The upstream fixes for the three MLX offgraph failures (pytorch#22627) and two
LoRA
cleanup failures (pytorch#22632) observed at `dd042e5537` are now incorporated.
The old
DFlash/QNN failures occurred during dependency downloads. Fresh runs of
all
seven previously failing jobs have been scheduled and must complete
before
those failures can be considered cleared. See the [current PR
checks](https://github.com/pytorch/executorch/pull/22620/checks).
### Follow-up implementation issues
- pytorch#22681: correct the deprecated llama `seq_len` CLI help
- pytorch#22682: honor standard Android SDK environment variables
- pytorch#22683: probe the usable Metal compiler in Apple CMake presets
- pytorch#22684: avoid unnecessary portable-kernel linkage from Core ML
- pytorch#22685: align the LLM image tensor layout contract with runtime
behavior
- pytorch#22686: declare SwiftPM system-framework dependencies
- pytorch#22687: add the structured deployment-story issue form1 parent 7bc5e0e commit bba7552
32 files changed
Lines changed: 1272 additions & 855 deletions
File tree
- backends/mlx
- docs/source
- backends
- mlx
- vulkan
- tutorials
- llm
- examples
- models
- lfm2
- qwen3
- yolo26
- vulkan
- extension
- llm/runner
- wasm
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
4 | 4 | | |
5 | 5 | | |
6 | 6 | | |
7 | | - | |
8 | 7 | | |
9 | | - | |
| 8 | + | |
10 | 9 | | |
11 | 10 | | |
12 | 11 | | |
| |||
24 | 23 | | |
25 | 24 | | |
26 | 25 | | |
27 | | - | |
| 26 | + | |
28 | 27 | | |
29 | 28 | | |
30 | 29 | | |
| |||
Large diffs are not rendered by default.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
14 | 14 | | |
15 | 15 | | |
16 | 16 | | |
17 | | - | |
18 | | - | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
19 | 20 | | |
20 | 21 | | |
21 | 22 | | |
22 | 23 | | |
23 | | - | |
| 24 | + | |
24 | 25 | | |
25 | 26 | | |
26 | | - | |
27 | | - | |
| 27 | + | |
28 | 28 | | |
29 | | - | |
30 | | - | |
| 29 | + | |
| 30 | + | |
31 | 31 | | |
32 | 32 | | |
33 | 33 | | |
| 34 | + | |
34 | 35 | | |
35 | 36 | | |
36 | 37 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
5 | 60 | | |
6 | 61 | | |
7 | 62 | | |
8 | 63 | | |
9 | 64 | | |
10 | | - | |
| 65 | + | |
11 | 66 | | |
12 | 67 | | |
13 | 68 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
28 | 28 | | |
29 | 29 | | |
30 | 30 | | |
31 | | - | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
32 | 34 | | |
33 | 35 | | |
34 | 36 | | |
35 | 37 | | |
36 | | - | |
| 38 | + | |
37 | 39 | | |
38 | 40 | | |
39 | | - | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
40 | 44 | | |
41 | 45 | | |
42 | 46 | | |
| 47 | + | |
43 | 48 | | |
44 | 49 | | |
45 | 50 | | |
| |||
54 | 59 | | |
55 | 60 | | |
56 | 61 | | |
57 | | - | |
| 62 | + | |
58 | 63 | | |
59 | 64 | | |
60 | 65 | | |
| |||
63 | 68 | | |
64 | 69 | | |
65 | 70 | | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
66 | 75 | | |
67 | 76 | | |
68 | 77 | | |
69 | 78 | | |
70 | 79 | | |
71 | 80 | | |
72 | 81 | | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
73 | 85 | | |
74 | 86 | | |
75 | 87 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
92 | 92 | | |
93 | 93 | | |
94 | 94 | | |
95 | | - | |
| 95 | + | |
96 | 96 | | |
97 | | - | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
98 | 100 | | |
99 | 101 | | |
100 | 102 | | |
| 103 | + | |
101 | 104 | | |
102 | 105 | | |
| 106 | + | |
| 107 | + | |
103 | 108 | | |
104 | 109 | | |
105 | 110 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
44 | 44 | | |
45 | 45 | | |
46 | 46 | | |
47 | | - | |
| 47 | + | |
48 | 48 | | |
49 | 49 | | |
50 | 50 | | |
51 | 51 | | |
52 | 52 | | |
53 | 53 | | |
54 | | - | |
| 54 | + | |
55 | 55 | | |
56 | 56 | | |
57 | 57 | | |
| |||
136 | 136 | | |
137 | 137 | | |
138 | 138 | | |
139 | | - | |
140 | 139 | | |
141 | 140 | | |
142 | 141 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
25 | 25 | | |
26 | 26 | | |
27 | 27 | | |
28 | | - | |
29 | | - | |
30 | | - | |
31 | | - | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
32 | 32 | | |
33 | 33 | | |
34 | 34 | | |
| |||
47 | 47 | | |
48 | 48 | | |
49 | 49 | | |
50 | | - | |
51 | | - | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
52 | 53 | | |
53 | 54 | | |
54 | 55 | | |
| |||
85 | 86 | | |
86 | 87 | | |
87 | 88 | | |
88 | | - | |
| 89 | + | |
89 | 90 | | |
90 | 91 | | |
91 | 92 | | |
92 | 93 | | |
93 | 94 | | |
94 | 95 | | |
95 | 96 | | |
96 | | - | |
| 97 | + | |
97 | 98 | | |
98 | 99 | | |
99 | 100 | | |
| |||
110 | 111 | | |
111 | 112 | | |
112 | 113 | | |
113 | | - | |
114 | | - | |
115 | | - | |
116 | | - | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
117 | 117 | | |
118 | 118 | | |
119 | 119 | | |
120 | | - | |
| 120 | + | |
121 | 121 | | |
122 | | - | |
123 | 122 | | |
124 | 123 | | |
125 | 124 | | |
126 | 125 | | |
127 | | - | |
128 | | - | |
129 | | - | |
130 | | - | |
131 | | - | |
132 | | - | |
133 | | - | |
134 | | - | |
135 | | - | |
136 | | - | |
137 | | - | |
138 | | - | |
139 | | - | |
| 126 | + | |
140 | 127 | | |
141 | 128 | | |
142 | 129 | | |
| |||
156 | 143 | | |
157 | 144 | | |
158 | 145 | | |
159 | | - | |
160 | | - | |
161 | | - | |
162 | | - | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
163 | 150 | | |
164 | | - | |
| 151 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
38 | 38 | | |
39 | 39 | | |
40 | 40 | | |
41 | | - | |
| 41 | + | |
42 | 42 | | |
43 | 43 | | |
44 | 44 | | |
| |||
0 commit comments