Docs: consolidate build-from-source and GPU backend guide

Offen Anfängerfreundlich

#2,314 erstellt am 19.6.2026 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit: 2/5
Geschätzter Aufwand: 1-3 Stunden
Anfängerfreundlichkeit: 75/100

Issue-Typ: Dokumentation
Klarheit: Klar beschrieben
Aktivitätsstatus: Ruhig
Tech-Stack: cmake, python
Bereich: build-system, documentation

Rechercherichtung

Das Issue weist auf die Konsolidierung der Build-Dokumentation hin, wahrscheinlich in docs/build.md oder einer neuen Datei docs/gpu.md. Beginnen Sie mit der Überprüfung der vorhandenen README, CONTRIBUTING.md und der verlinkten GitHub-Issues (#2013, #695, #721, #756), um die aktuell verstreuten Informationen zu verstehen. Erstellen Sie dann eine klare Tabelle der CMAKE_ARGS für jedes GPU-Backend und fügen Sie Schritte zur Fehlerbehebung für häufige Fehler hinzu. Überprüfen Sie die Änderungen, indem Sie das Projekt mit einem GPU-Backend bauen, um sicherzustellen, dass die Anweisungen funktionieren.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

Problem

The build-from-source documentation is spread across README, CONTRIBUTING.md, and many GitHub issues (e.g. #2013, #695, #721, #756). Users with newer GPUs (RTX 50-series, sm_120) or uncommon CUDA versions repeatedly hit the same build failures because the docs lack:

A CMAKE_ARGS mapping table showing which flag to set for each GPU backend
CUDA version compatibility notes (e.g., CUDA 12.9+ requires specific cmake workarounds)
The minimum/maximum supported CUDA toolkit versions
How to verify the build actually used the GPU (simple Python snippet to check backend)

Suggested improvements

In docs/build.md (or a new docs/gpu.md):

| Backend | CMAKE_ARGS                                    | GPU Requirements              |
|---------|-----------------------------------------------|-------------------------------|
| CUDA    | -DGGML_CUDA=ON                                | NVIDIA GPU, CUDA >= 11.3      |
| Metal   | -DGGML_METAL=ON (default on macOS)            | Apple Silicon or AMD GPU      |
| Vulkan  | -DGGML_VULKAN=ON                              | Vulkan 1.2+ capable GPU       |
| SYCL    | -DGGML_SYCL=ON -DGGML_SYCL_TARGET=INTEL       | Intel Arc / Iris Xe           |
| HIP     | -DGGML_HIPBLAS=ON                             | AMD ROCm-compatible GPU       |

And a troubleshooting section for the most common build errors (CMake not finding CUDA, nvcc version mismatch, sm_120 not recognized).

Value

Consolidating this reduces the "can't install with GPU" issues that currently fill the tracker.

Vorherrschende Sprache: Python
Sterne: 10.6k
Forks: 1.5k
Ø Merge: 6 Std. 43 Min.
Gemergte PRs (30 T.): 2

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
Forken Sie das Repository und arbeiten Sie in einem Branch.
Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus abetlen/llama-cpp-python

Seven llama_sampler_init_* bindings admit keyword arguments that the ctypes function object silently drops Offen

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 88/100

abetlen/llama-cpp-python#2371 · Erstellt am 22.9.2026
uv add llama-cpp-python wheels fails for versions above 0.3.30 Offen

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 65/100

abetlen/llama-cpp-python#2352 · Erstellt am 31.7.2026
Llama.embed() calls LlamaBatch.add_sequence with old 3-arg signature; missing logits_array Offen

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 65/100

abetlen/llama-cpp-python#2211 · 2 Kommentare · Erstellt am 09.5.2026
Llama() silently accepts and discards `embedding` kwarg; .embed() then raises confusingly Offen

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 65/100

abetlen/llama-cpp-python#2210 · Erstellt am 09.5.2026
Improve error messages Offen

Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 65/100

abetlen/llama-cpp-python#2145 · Erstellt am 22.3.2026

Alle Issues in abetlen/llama-cpp-python