Servizi di modelli locali

models.providers.<id>.localService consente a OmeniaClaw di avviare su richiesta un server di modelli locale di proprietà del provider. È una configurazione a livello di provider: quando il modello selezionato appartiene a quel provider, OmeniaClaw verifica il servizio, avvia il processo se l'endpoint non è attivo, attende che sia pronto, quindi invia la richiesta del modello.

Usalo per server locali costosi da mantenere in esecuzione tutto il giorno, oppure per configurazioni manuali in cui la selezione del modello dovrebbe bastare per avviare il backend.

Come funziona

1. Una richiesta di modello viene risolta in un provider configurato.
2. Se quel provider ha localService, OmeniaClaw verifica healthUrl.
3. Se la verifica riesce, OmeniaClaw usa il server esistente.
4. Se la verifica fallisce, OmeniaClaw avvia command con args.
5. OmeniaClaw controlla periodicamente la disponibilità finché readyTimeoutMs non scade.
6. La richiesta del modello viene inviata tramite il normale trasporto del provider.
7. Se OmeniaClaw ha avviato il processo e idleStopMs è positivo, il processo viene arrestato dopo che l'ultima richiesta in corso è rimasta inattiva per quel tempo.

OmeniaClaw non installa launchd, systemd, Docker o un daemon per questo. Il server è un processo figlio del processo OmeniaClaw che ne ha avuto bisogno per primo.

Forma della configurazione

{  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,          },        ],      },    },  },}

Campi

• command: percorso assoluto dell'eseguibile. La ricerca tramite shell non viene usata.
• args: argomenti del processo. Non vengono applicati espansione della shell, pipe, globbing o regole di quoting.
• cwd: directory di lavoro facoltativa per il processo.
• env: variabili di ambiente facoltative unite all'ambiente del processo OmeniaClaw.
• healthUrl: URL di disponibilità. Se omesso, OmeniaClaw aggiunge /models a baseUrl, quindi http://127.0.0.1:8000/v1 diventa http://127.0.0.1:8000/v1/models.
• readyTimeoutMs: scadenza per la disponibilità all'avvio. Predefinito: 120000.
• idleStopMs: ritardo di arresto per inattività per i processi avviati da OmeniaClaw. 0 o omesso mantiene il processo attivo finché OmeniaClaw non esce.

Esempio Inferrs

Inferrs è un backend /v1 personalizzato compatibile con OpenAI, quindi la stessa API di servizio locale funziona con la voce provider inferrs.

{  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,            },          },        ],      },    },  },}

Sostituisci command con il risultato di which inferrs sulla macchina che esegue OmeniaClaw.

Esempio ds4

{  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: [],      },    },  },}

Note operative

• Un processo OmeniaClaw gestisce il processo figlio che ha avviato. Un altro processo OmeniaClaw che vede già attivo lo stesso URL di disponibilità lo riutilizzerà senza adottarlo.
• L'avvio è serializzato per comando del provider e set di argomenti, quindi le richieste concorrenti non generano server duplicati per la stessa configurazione.
• Le risposte in streaming attive mantengono un lease; l'arresto per inattività attende finché la gestione del corpo della risposta non è completa.
• Usa timeoutSeconds sui provider locali lenti in modo che gli avvii a freddo e le generazioni lunghe non raggiungano il timeout predefinito della richiesta del modello.
• Usa un healthUrl esplicito se il server espone la disponibilità in un punto diverso da /v1/models.

Correlati