GGUF-Modell in Ollama importieren und Fehler beheben

Zwei Möglichkeiten, ein GGUF-Modell in Ollama zu importieren

Es gibt zwei Möglichkeiten, ein GGUF-Modell in Ollama zu importieren. Welche davon geeignet ist, hängt davon ab, wo sich die Datei aktuell befindet. Liegt das Modell in einem Hugging-Face-Repository, lädt ein einzelner ollama run-Befehl das Modell herunter und startet es. Eine Modelfile ist dafür nicht erforderlich. Befindet sich die .gguf-Datei bereits auf der Festplatte Ihres Servers, erstellen Sie eine zweizeilige Modelfile und führen ollama create aus.

Beide Wege führen zum selben Ergebnis: einem benannten Modell in Ihrer lokalen Ollama-Bibliothek, das ollama run und über die Ollama-API bereitgestellt werden kann. Verwenden Sie den ersten Weg, wenn jemand anderes die Datei veröffentlicht hat. Verwenden Sie den zweiten Weg, wenn Sie das Modell selbst quantisiert haben, wenn die Datei über scp oder rsync auf den Server gelangt ist oder wenn der Rechner Hugging Face nicht erreichen kann.

Eine GGUF-Datei ist eine Binärdatei, die Gewichte, Tokenizer und Modellmetadaten gemeinsam enthält. Es handelt sich um das Format, das llama.cpp liest. Ollama basiert auf llama.cpp. Deshalb gibt es für fast jedes Open Model eine GGUF-Konvertierung aus der Community. Ollama lädt keinen Ordner mit .safetensors-Gewichten direkt. Der Konvertierungsschritt ist daher erforderlich.

Im Folgenden wird vorausgesetzt, dass Ollama bereits installiert ist und der Dienst läuft. Falls das nicht der Fall ist, beginnen Sie mit Ollama auf einem VPS installieren und kehren Sie anschließend hierher zurück. Führen Sie zuerst ollama list aus. Wenn der Befehl statt eines Verbindungsfehlers eine Tabelle zurückgibt, auch wenn sie leer ist, läuft der Server und der Rest dieser Anleitung funktioniert.

Route 1: GGUF von Hugging Face ohne Modelfile ausführen

Ollama kann ein GGUF direkt aus einem Hugging-Face-Repository laden. Der Befehl besteht aus dem Repository-Pfad mit dem Präfix hf.co/:

ollama run hf.co/{username}/{repository}

Sowohl hf.co als auch huggingface.co funktionieren als Domainname. Ein echtes Beispiel aus der Hugging-Face-Dokumentation:

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF

Beim ersten Start wird die Datei heruntergeladen. Die Chat-Eingabeaufforderung erscheint daher erst nach Abschluss des Downloads. Danach befindet sich das Modell in Ihrer lokalen Bibliothek und startet schnell. Öffnen Sie eine zweite Shell und führen Sie ollama list aus, um den Namen anzuzeigen, unter dem das Modell gespeichert wurde. Dieser Name ist die gesamte Zeichenfolge hf.co/... einschließlich des Tags und daher bei jedem Aufruf umständlich einzugeben. Vergeben Sie einen kurzen Alias:

ollama cp hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF my-llama
ollama run my-llama

Diese Route funktioniert nur für Repositories, die tatsächlich GGUF-Dateien enthalten. Ein Repository, das ausschließlich .safetensors-Gewichte veröffentlicht, stellt Ollama keine abrufbare Datei bereit. In diesem Fall benötigen Sie den weiter unten beschriebenen Konvertierungsschritt.

Welche Quantisierung wählt Ollama?

Die am 25 August 2026 gelesene Ollama-Dokumentation von Hugging Face nennt den Standard ausdrücklich: „Standardmäßig wird das Quantisierungsschema Q4_K_M verwendet, sofern es im Modell-Repository vorhanden ist. Andernfalls wählen wir standardmäßig einen geeigneten Quantisierungstyp aus, der im Repository vorhanden ist.“ Ein Repository mit zehn Quanten liefert Ihnen daher Q4_K_M. Fehlt Q4_K_M, erhalten Sie eine von Ollama getroffene Auswahl. Lesen Sie diese Seite erneut, bevor Sie sich darauf verlassen, da sich Standardwerte ändern können.

Fordern Sie eine bestimmte Quantisierung an, indem Sie sie als Tag hinzufügen:

ollama run hf.co/{username}/{repository}:{quantization}

ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Q8_0
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:iq3_m
ollama run hf.co/bartowski/Llama-3.2-3B-Instruct-GGUF:Llama-3.2-3B-Instruct-IQ3_M.gguf

Der Name der Quantisierung unterscheidet nicht zwischen Groß- und Kleinschreibung. :iq3_m und :IQ3_M bezeichnen daher dasselbe. Sie können als Tag auch den exakten Dateinamen angeben. Das ist die sichere Form, wenn die Kurzbezeichnungen in einem Repository mehrdeutig sind. Der Tag muss eine Datei bezeichnen, die in diesem Repository vorhanden ist. Öffnen Sie daher die Registerkarte „Files and versions“ und lesen Sie die tatsächlichen Dateinamen ab, bevor Sie einen davon eingeben. Welche Quantisierung Sie benötigen, hängt von Speicherbedarf und Qualität ab. Der Unterschied zwischen Q4, Q8 und FP16 erläutert diesen Zielkonflikt ausführlich.

Zweiter Weg: Eine .gguf-Datei von der eigenen Festplatte importieren

Wenn sich die Datei bereits auf dem Server befindet, benötigen Sie ein Modelfile. Es kann aus einer einzigen Zeile bestehen. Erstellen Sie ein Verzeichnis, legen Sie das Modelfile darin ab und verweisen Sie mit FROM auf die Datei:

mkdir -p ~/models/my-model
cd ~/models/my-model

FROM /home/you/models/my-model-Q4_K_M.gguf

Speichern Sie die Datei als Modelfile und erstellen Sie anschließend das Modell:

ollama create my-model

ollama create liest standardmäßig eine Datei mit dem Namen Modelfile aus dem aktuellen Verzeichnis. Verwenden Sie -f, wenn Ihre Datei einen anderen Namen hat oder sich an einem anderen Ort befindet, wie in ollama create my-model -f /home/you/models/my-model/Modelfile. Führen Sie ollama create --help aus, um das Flag und seinen Standardwert für Ihren Build anzuzeigen. Der Pfad in FROM kann absolut oder relativ zum Modelfile sein. Daher funktioniert FROM ./my-model-Q4_K_M.gguf, wenn sich beide Dateien im selben Verzeichnis befinden. Mit einem absoluten Pfad vermeiden Sie diese Frage vollständig.

Prüfen Sie das Ergebnis, bevor Sie ihm vertrauen:

ollama list
ollama show my-model
ollama run my-model "Reply with one short sentence."

ollama list sollte jetzt my-model enthalten. ollama show my-model gibt die Architektur, die Anzahl der Parameter, die Kontextlänge und die Quantisierung aus, die Ollama aus den Metadaten der Datei gelesen hat. Lesen Sie diese Werte aus, statt dem Dateinamen zu vertrauen, denn ein Dateiname ist eine Zeichenfolge, die jemand manuell eingegeben hat. Wenn das Modell auf Ihren Test-Prompt in normaler Sprache antwortet und anschließend stoppt, war der Import erfolgreich. Falls nicht, wechseln Sie zum folgenden Abschnitt über Templates, denn das ist fast immer die Ursache.

Beachten Sie den Speicherplatzbedarf: ollama create kopiert die GGUF-Datei in Ollamas eigenen Modellspeicher, statt auf die Datei an ihrem bisherigen Speicherort zu verweisen. Die Gewichte belegen so lange zweimal Speicherplatz, bis Sie das Original entfernen. Löschen Sie die Quelldatei, sobald ollama run my-model funktioniert, oder bewahren Sie sie an einem Speicherort auf, für den Sie nicht doppelt Speicherplatz bezahlen. Wo Ollama seine Modelle auf der Festplatte speichert beschreibt die Verzeichnisstruktur und das Verschieben des Modells.

Wann --quantize angewendet wird und wann nicht

ollama create besitzt ein --quantize-Flag. Es ist für genau einen Fall vorgesehen: ein Quellmodell in FP16 oder FP32, also Gewichte mit voller Präzision. Die Importdokumentation von Ollama nennt q8_0 sowie die k-means-Varianten q4_K_S und q4_K_M als Zielwerte.

ollama create --quantize q4_K_M my-model

Verwenden Sie dieses Flag nicht für eine Datei, die bereits quantisiert ist. Ein .gguf, dessen Name Q4_K_M oder Q5_K_S enthält, hat diesen Schritt bereits durchlaufen. Das Flag kann dann nichts mehr tun. Quantisierung ist eine Umwandlung von höherer in niedrigere Präzision. Daher gibt es keinen Weg von Q4 zurück zu Q8. Wenn Ihre Quelle ein Hugging-Face-Repository mit .safetensors-Dateien ist, konvertieren Sie sie zunächst mit convert_hf_to_gguf.py aus dem llama.cpp-Repository. Dabei handelt es sich um das Tool, auf das die Ollama-Dokumentation verweist. Importieren Sie anschließend die GGUF-Datei, die dieses Skript erzeugt. Wie Ollama und llama.cpp zusammenhängen erklärt, warum das Konvertierungsskript zum anderen Projekt gehört.

Warum antwortet ein importiertes GGUF mit unverständlichem Text oder hört nie auf?

Das ist der Fehler, den die meisten Importanleitungen auslassen. Sie werden ihm wahrscheinlich begegnen. Die Symptome sehen nach einem defekten Modell aus. Steuerungstoken erscheinen als sichtbarer Text in der Antwort, beispielsweise Zeichenfolgen wie <|im_start|>assistant oder <|end|>. Das Modell antwortet, formuliert anschließend eine neue Benutzerfrage und beantwortet auch diese. Die Generierung läuft weiter, bis Sie Ctrl+C drücken.

Das Modell ist in Ordnung. Die Chatvorlage ist falsch. Eine Chatvorlage ist der Wrapper, der Ihre Nachricht in genau die Tokenfolge umwandelt, mit der das Modell trainiert wurde. Sie enthält eigene Marker dafür, wo die Systemanweisung endet und der Benutzerturn beginnt. Ollama wählt automatisch eine Vorlage aus. Die Dokumentation sagt, dass anhand der integrierten tokenizer.chat_template-Metadaten in der GGUF-Datei „automatically from a list of commonly used templates“ eine Vorlage ausgewählt wird. Fehlen diese Metadaten oder passt ihr Wert zu keinem Eintrag in der Liste, erhalten Sie einen generischen Wrapper. Das Modell sieht dann eine Prompt-Struktur, die seiner Trainingsstruktur nicht entspricht. Deshalb erreicht es nie den End-of-Turn-Marker, bei dem es gelernt hat, die Generierung zu beenden.

Geben Sie die von Ollama tatsächlich ausgewählte Vorlage aus:

ollama show --template my-model
ollama show --modelfile my-model

Eine leere oder offensichtlich generische Vorlage bestätigt das Problem. Schreiben Sie die Vorlage selbst in die Modelfile:

FROM /home/you/models/my-model-Q4_K_M.gguf

TEMPLATE """{{ if .System }}<|system|>
{{ .System }}<|end|>
{{ end }}{{ if .Prompt }}<|user|>
{{ .Prompt }}<|end|>
{{ end }}<|assistant|>
{{ .Response }}<|end|>"""

PARAMETER stop "<|end|>"

Erstellen Sie das Modell mit ollama create my-model neu und senden Sie denselben Testprompt erneut. Der Parameter stop ist eine Sicherheitsbegrenzung. Er weist Ollama an, die Generierung zu beenden, sobald diese Zeichenfolge erscheint. Dadurch endet das Problem mit der endlosen Generierung, während Sie die Vorlage noch anpassen. Wenn die Antwort weiterläuft, weil kein von Ihnen angegebener Marker erscheint, beendet eine num_predict-Obergrenze die Generierung nach einer festen Tokenanzahl, unabhängig davon, was die Vorlage ausgibt.

Die Vorlage muss eine Go-Vorlage und keine Jinja-Vorlage sein. Die Dokumentation von Hugging Face weist ausdrücklich darauf hin. Das ist wichtig, weil das Feld tokenizer.chat_template im ursprünglichen Modell-Repository Jinja enthält. Unverändertes Einfügen funktioniert nicht. Die Syntax von Ollama verwendet drei Variablen: {{ .System }} für die Systemanweisung, {{ .Prompt }} für die Benutzernachricht und {{ .Response }} für die Antwort des Modells. Suchen Sie die tatsächlichen Turn-Marker des Modells in seiner Model Card oder in tokenizer_config.json. Übertragen Sie sie anschließend manuell in diese Go-Syntax.

Eine Abkürzung erspart Ihnen den größten Teil dieser Arbeit. Viele Modelle verwenden dasselbe Prompt-Format. Wenn ein anderes Modell in Ihrer Bibliothek dasselbe Format verwendet, führen Sie ollama show --template für dieses Modell aus und übernehmen Sie die ausgegebene Vorlage.

Die Dateien template, system und params in einem Hugging-Face-Repository

Die Hugging-Face-Variante bietet dieselben Einstellungen über Dateien im Repository statt über Anweisungen in einer Modelfile. Wenn Sie das Repository besitzen oder Ihre eigene Quantisierung veröffentlichen, fügen Sie diese Dateien dort hinzu. Jede ollama run hf.co/... übernimmt sie dann.

• Eine Datei namens template enthält das Go-Template. Es gilt weiterhin: Go, nicht Jinja.
• Eine Datei namens system enthält den System-Prompt.
• Eine Datei namens params enthält Sampling-Parameter und muss gültiges JSON enthalten.

Eine minimale params-Datei:

{
  "stop": ["<|end|>"],
  "temperature": 0.7
}

Wenn Sie das Repository nicht besitzen, können Sie diese Dateien nicht hinzufügen. Laden Sie das Modell einmal herunter, führen Sie ollama show --modelfile hf.co/... aus, um die bereitgestellte Konfiguration auszugeben, und speichern Sie diese Ausgabe als Modelfile. Die Zeile FROM verweist auf den Blob, den Ollama bereits heruntergeladen hat. Sie können daher die Zeilen TEMPLATE und PARAMETER bearbeiten und anschließend ollama create ausführen, um eine korrigierte lokale Kopie zu erstellen, ohne erneut etwas herunterzuladen. Das ist die übliche Reparatur für eine fehlerhafte Quantisierung eines anderen Anbieters.

So importieren Sie ein privates GGUF-Repository

Für ein privates Repository muss der SSH-Schlüssel von Ollama in Ihrem Hugging-Face-Konto hinterlegt sein. Die dokumentierte Methode für diesen Weg verwendet einen SSH-Schlüssel und kein API-Token. Ein bereits vorhandenes Token öffnet das Repository daher nicht.

Geben Sie den öffentlichen Schlüssel aus. Auf einem Linux-Server, auf dem Ollama mit dem offiziellen Skript installiert wurde, wird der Dienst als Benutzer ollama ausgeführt. Der Schlüssel liegt deshalb im Home-Verzeichnis dieses Benutzers:

sudo cat /usr/share/ollama/.ollama/id_ed25519.pub

Wenn Sie ollama serve selbst als Ihr eigener Benutzer starten, lautet der Pfad stattdessen ~/.ollama/id_ed25519.pub. Kopieren Sie die vollständige Zeile, öffnen Sie die Kontoeinstellungen von Hugging Face unter https://huggingface.co/settings/keys, und fügen Sie sie als neuen SSH-Schlüssel hinzu. Der normale Befehl funktioniert dann auch für Ihre privaten Repositories:

ollama run hf.co/{username}/{repository}

Wenn der Pull nach dem Hinzufügen des Schlüssels weiterhin fehlschlägt, haben Sie wahrscheinlich die falsche Datei ausgegeben. Der Server führt den Download aus und verwendet dabei seinen eigenen Schlüssel. Ein über systemd gestarteter Server liest niemals die Datei ~/.ollama Ihres Benutzers. Der Schlüssel in Ihrem Home-Verzeichnis ist daher nicht der Schlüssel, den Hugging Face sieht.

Passt das Modell auf Ihre VPS?

Entscheidend sind die Dateigröße auf dem Datenträger und der Speicherbedarf des Kontextfensters. Die Gewichte werden ungefähr in der Größe, die sie in der Datei belegen, in den Arbeitsspeicher geladen. Zusätzlich wird Speicher für den Kontext reserviert. Dieser Bedarf wächst mit der Anzahl der Tokens, die Sie zulassen. Führen Sie ollama list aus, um die von Ollama erfasste Modellgröße abzurufen. Vergleichen Sie sie mit free -h auf dem Server. Lassen Sie außerdem ausreichend Speicher für das Betriebssystem und alle anderen Dienste frei, die auf dem Server laufen. Wenn Sie diese Berechnung lieber anhand eines realen Modells nachvollziehen möchten, nennt Nemotron 3.5 Lightning auf einer VPS ausführen den genauen Tag für den Pull, den benötigten RAM und ob ein Server ohne GPU die Verarbeitung bewältigt.

Der Kontext wird häufig vergessen. Ein Modell kann mit dem Standardfenster geladen werden, aber nach einer Erhöhung von num_ctx fehlschlagen, weil der dafür reservierte Speicher mit der von Ihnen festgelegten Fenstergröße skaliert. num_ctx festlegen und die Speicherkosten verstehen enthält die Größenberechnung. Wenn der gesamte Speicherbedarf zu groß ist, verwenden Sie in der Regel eine kleinere Quantisierung desselben Modells. Dieser Kompromiss wird in dem Vergleich von Q4 und Q8 behandelt.

Der Fehler bleibt nicht unbemerkt. Auf einer VPS ohne GPU beendet der Out-of-Memory-Killer des Kernels den Prozess. journalctl -u ollama -n 50 zusammen mit dmesg zeigt, dass der Prozess beendet wurde. Auf einem Server mit GPU gibt ollama ps eine PROCESSOR-Spalte aus. Sie zeigt, ob das geladene Modell im GPU-Speicher, im Arbeitsspeicher des Systems oder auf beide Speicherarten verteilt liegt. Ein Modell, das teilweise in den Arbeitsspeicher des Systems ausgelagert wurde, beantwortet weiterhin Anfragen, aber langsam. Tokens pro Sekunde messen macht aus „langsam“ eine Zahl, die Sie zwischen verschiedenen Quantisierungen vergleichen können.

Prüfen Sie, was Sie importiert haben

Führen Sie nach jedem Import diese vier Befehle in dieser Reihenfolge aus:

ollama list
ollama show my-model
ollama show --modelfile my-model
ollama run my-model "Reply with one short sentence."

ollama list bestätigt, dass das Modell vorhanden ist, und zeigt die von Ollama erfasste Größe an. ollama show bestätigt, dass Ollama die benötigten Metadaten aus der GGUF-Datei gelesen hat. ollama show --modelfile bestätigt, welches Template und welche Parameter tatsächlich verwendet werden. Diese Prüfung erkennt die Ursache für fehlerhafte Ausgaben, bevor Ihre Benutzer darauf stoßen. Der Test-Prompt prüft die gesamte Verarbeitungskette, weil ein Modell mit einem fehlerhaften Template bereits bei der kürzesten Anfrage fehlschlägt. Sobald dieser Prompt eine korrekte Antwort liefert, entspricht der von Ihnen vergebene Modellname dem Namen, den Sie auch für andere Clients verwenden, die mit der Ollama API kommunizieren, einschließlich eines auf Ihren eigenen Server ausgerichteten Coding-Agenten. Entfernen Sie einen fehlerhaften Import mit ollama rm my-model und erstellen Sie ihn erneut. Dieser Befehl löscht Ollamas Kopie und lässt Ihre Quelle .gguf unverändert.

FAQ

Kann ich ein GGUF in Ollama importieren, ohne eine Modelfile zu schreiben?

Ja, wenn die Datei in einem Hugging-Face-Repository liegt. ollama run hf.co/{username}/{repository} ruft sie direkt ab und führt sie aus, und ollama run hf.co/{username}/{repository}:{quantization} wählt eine bestimmte Quantisierung aus. Eine Modelfile wird nur für ein .gguf benötigt, das bereits auf Ihrer eigenen Festplatte liegt. In diesem Fall kann sie aus der einzelnen Zeile FROM /path/to/file.gguf bestehen, gefolgt von ollama create my-model.

Welche Quantisierung lädt Ollama, wenn ich keine angebe?

Die am 25 August 2026 gelesene Dokumentation von Hugging Face sagt, dass Q4_K_M verwendet wird, wenn diese Quantisierung im Repository vorhanden ist. Andernfalls wählt Ollama einen geeigneten Quantisierungstyp aus, der im Repository vorhanden ist. Fügen Sie ein Tag wie :Q8_0 hinzu, um die Auswahl zu steuern. Prüfen Sie mit ollama show <model>, was tatsächlich abgerufen wurde. Der Befehl gibt die Quantisierung aus den Metadaten der Datei aus und nicht aus ihrem Namen.

Warum wiederholt mein importiertes Modell Text oder beendet die Generierung nie?

Das Chat-Template stimmt nicht mit dem Modell überein. Ollama wählt automatisch ein Template anhand der tokenizer.chat_template-Metadaten im GGUF aus. Wenn diese Metadaten fehlen oder nicht erkannt werden, verwendet Ollama eine generische Hülle. Dadurch sieht das Modell das End-of-Turn-Marker nicht, mit dem es trainiert wurde. Geben Sie das aktuelle Template mit ollama show --template <model> aus. Fügen Sie anschließend einen TEMPLATE-Block und eine PARAMETER stop-Zeile zur Modelfile hinzu und führen Sie ollama create erneut aus. Schreiben Sie das Template als Go-Template. Das Jinja-Template aus dem ursprünglichen Repository funktioniert nicht.

Sollte ich --quantize für ein heruntergeladenes GGUF verwenden?

Nein. --quantize konvertiert während ollama create eine FP16- oder FP32-Quelle. Eine Datei, deren Name bereits eine Quantisierung wie Q4_K_M enthält, wurde bereits konvertiert. Durch eine erneute Quantisierung lässt sich die Präzision nicht wiederherstellen. Ein Weg zurück zu höherer Präzision existiert nicht. Verwenden Sie das Flag nur, wenn Sie safetensors selbst in ein GGUF mit voller Präzision konvertiert haben und nun eine kleinere Datei erstellen möchten.

Wie rufe ich ein privates GGUF-Repository ab?

Fügen Sie den öffentlichen SSH-Schlüssel von Ollama Ihrem Hugging-Face-Konto hinzu. Geben Sie ihn bei einer standardmäßigen Linux-Installation mit sudo cat /usr/share/ollama/.ollama/id_ed25519.pub aus. Wenn Sie den Server als eigener Benutzer ausführen, verwenden Sie ~/.ollama/id_ed25519.pub. Fügen Sie den Schlüssel anschließend auf der Seite für die SSH-Schlüssel Ihres Kontos hinzu. Danach funktioniert ollama run hf.co/{username}/{repository} mit Ihren privaten Repositories und mit Repositories in einer Organisation, der Sie angehören.