Lokale Modelldienste

models.providers.<id>.localService ermöglicht OmeniaClaw, bei Bedarf einen Provider-eigenen lokalen Modellserver zu starten. Es handelt sich um eine Konfiguration auf Provider-Ebene: Wenn das ausgewählte Modell zu diesem Provider gehört, prüft OmeniaClaw den Dienst, startet den Prozess, falls der Endpoint nicht erreichbar ist, wartet auf die Bereitschaft und sendet dann die Modellanfrage.

Verwenden Sie dies für lokale Server, deren dauerhafter Betrieb den ganzen Tag über teuer ist, oder für manuelle Setups, bei denen die Modellauswahl ausreichen soll, um das Backend zu starten.

Funktionsweise

1. Eine Modellanfrage wird einem konfigurierten Provider zugeordnet.
2. Wenn dieser Provider localService hat, prüft OmeniaClaw healthUrl.
3. Wenn die Prüfung erfolgreich ist, verwendet OmeniaClaw den vorhandenen Server.
4. Wenn die Prüfung fehlschlägt, startet OmeniaClaw command mit args.
5. OmeniaClaw fragt die Bereitschaft ab, bis readyTimeoutMs abläuft.
6. Die Modellanfrage wird über den normalen Provider-Transport gesendet.
7. Wenn OmeniaClaw den Prozess gestartet hat und idleStopMs positiv ist, wird der Prozess beendet, nachdem die letzte laufende Anfrage für diesen Zeitraum inaktiv war.

OmeniaClaw installiert hierfür kein launchd, systemd, Docker oder einen Daemon. Der Server ist ein Kindprozess des OmeniaClaw-Prozesses, der ihn zuerst benötigt hat.

Konfigurationsstruktur

{  models: {    providers: {      local: {        baseUrl: "http://127.0.0.1:8000/v1",        apiKey: "local-model",        api: "openai-completions",        timeoutSeconds: 300,        localService: {          command: "/absolute/path/to/server",          args: ["--host", "127.0.0.1", "--port", "8000"],          cwd: "/absolute/path/to/working-dir",          env: { LOCAL_MODEL_CACHE: "/absolute/path/to/cache" },          healthUrl: "http://127.0.0.1:8000/v1/models",          readyTimeoutMs: 180000,          idleStopMs: 0,        },        models: [          {            id: "my-local-model",            name: "My Local Model",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 131072,            maxTokens: 8192,          },        ],      },    },  },}

Felder

• command: absoluter Pfad zur ausführbaren Datei. Shell-Suche wird nicht verwendet.
• args: Prozessargumente. Es werden keine Shell-Erweiterung, Pipes, Globbing- oder Quoting- Regeln angewendet.
• cwd: optionales Arbeitsverzeichnis für den Prozess.
• env: optionale Umgebungsvariablen, die über die Umgebung des OmeniaClaw-Prozesses gelegt werden.
• healthUrl: Bereitschafts-URL. Wenn weggelassen, hängt OmeniaClaw /models an baseUrl an, sodass aus http://127.0.0.1:8000/v1 http://127.0.0.1:8000/v1/models wird.
• readyTimeoutMs: Frist für die Startbereitschaft. Standard: 120000.
• idleStopMs: Verzögerung für das Herunterfahren bei Inaktivität für von OmeniaClaw gestartete Prozesse. 0 oder Weglassen hält den Prozess am Leben, bis OmeniaClaw beendet wird.

Inferrs-Beispiel

Inferrs ist ein benutzerdefiniertes OpenAI-kompatibles /v1-Backend, daher funktioniert dieselbe lokale Dienst- API mit dem inferrs-Provider-Eintrag.

{  agents: {    defaults: {      model: { primary: "inferrs/google/gemma-4-E2B-it" },    },  },  models: {    mode: "merge",    providers: {      inferrs: {        baseUrl: "http://127.0.0.1:8080/v1",        apiKey: "inferrs-local",        api: "openai-completions",        timeoutSeconds: 300,        localService: {          command: "/opt/homebrew/bin/inferrs",          args: [            "serve",            "google/gemma-4-E2B-it",            "--host",            "127.0.0.1",            "--port",            "8080",            "--device",            "metal",          ],          healthUrl: "http://127.0.0.1:8080/v1/models",          readyTimeoutMs: 180000,          idleStopMs: 0,        },        models: [          {            id: "google/gemma-4-E2B-it",            name: "Gemma 4 E2B (inferrs)",            reasoning: false,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 131072,            maxTokens: 4096,            compat: {              requiresStringContent: true,            },          },        ],      },    },  },}

Ersetzen Sie command durch das Ergebnis von which inferrs auf der Maschine, auf der OmeniaClaw ausgeführt wird.

ds4-Beispiel

{  models: {    providers: {      ds4: {        baseUrl: "http://127.0.0.1:18000/v1",        apiKey: "ds4-local",        api: "openai-completions",        timeoutSeconds: 300,        localService: {          command: "/Users/you/Projects/oss/ds4/ds4-server",          args: [            "--model",            "/Users/you/Projects/oss/ds4/ds4flash.gguf",            "--host",            "127.0.0.1",            "--port",            "18000",            "--ctx",            "393216",          ],          cwd: "/Users/you/Projects/oss/ds4",          healthUrl: "http://127.0.0.1:18000/v1/models",          readyTimeoutMs: 300000,          idleStopMs: 0,        },        models: [],      },    },  },}

Betriebshinweise

• Ein OmeniaClaw-Prozess verwaltet den von ihm gestarteten Kindprozess. Ein anderer OmeniaClaw-Prozess, der dieselbe Health-URL bereits aktiv sieht, verwendet sie wieder, ohne sie zu übernehmen.
• Der Start wird pro Provider-Befehl und Argumentgruppe serialisiert, sodass gleichzeitige Anfragen keine doppelten Server für dieselbe Konfiguration erzeugen.
• Aktive Streaming-Antworten halten eine Lease; das Herunterfahren bei Inaktivität wartet, bis die Verarbeitung des Antwort-Bodys abgeschlossen ist.
• Verwenden Sie timeoutSeconds bei langsamen lokalen Providern, damit Kaltstarts und lange Generierungen nicht das Standard-Timeout für Modellanfragen erreichen.
• Verwenden Sie eine explizite healthUrl, wenn Ihr Server die Bereitschaft an einer anderen Stelle als /v1/models bereitstellt.

Verwandte Themen