Локальні сервіси моделей

models.providers.<id>.localService дозволяє OmeniaClaw запускати належний провайдеру локальний сервер моделей на вимогу. Це конфігурація на рівні провайдера: коли вибрана модель належить цьому провайдеру, OmeniaClaw перевіряє службу, запускає процес, якщо endpoint недоступний, чекає готовності, а потім надсилає запит до моделі.

Використовуйте це для локальних серверів, які дорого тримати запущеними цілий день, або для ручних налаштувань, де вибору моделі має бути достатньо, щоб підняти backend.

Як це працює

1. Запит до моделі зіставляється з налаштованим провайдером.
2. Якщо цей провайдер має localService, OmeniaClaw перевіряє healthUrl.
3. Якщо перевірка успішна, OmeniaClaw використовує наявний сервер.
4. Якщо перевірка неуспішна, OmeniaClaw запускає command з args.
5. OmeniaClaw опитує готовність, доки не сплине readyTimeoutMs.
6. Запит до моделі надсилається через звичайний транспорт провайдера.
7. Якщо OmeniaClaw запустив процес і idleStopMs додатний, процес зупиняється після того, як останній активний запит простоював так довго.

OmeniaClaw не встановлює для цього launchd, systemd, Docker або daemon. Сервер є дочірнім процесом процесу OmeniaClaw, якому він уперше знадобився.

Форма конфігурації

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

Поля

• command: абсолютний шлях до виконуваного файла. Пошук через shell не використовується.
• args: аргументи процесу. Розгортання shell, pipes, globbing або правила quoting не застосовуються.
• cwd: необов’язковий робочий каталог для процесу.
• env: необов’язкові змінні середовища, об’єднані поверх середовища процесу OmeniaClaw.
• healthUrl: URL готовності. Якщо пропущено, OmeniaClaw додає /models до baseUrl, тож http://127.0.0.1:8000/v1 стає http://127.0.0.1:8000/v1/models.
• readyTimeoutMs: граничний час очікування готовності під час запуску. Типово: 120000.
• idleStopMs: затримка вимкнення через простій для процесів, запущених OmeniaClaw. 0 або пропущене значення тримає процес активним, доки OmeniaClaw не завершиться.

Приклад Inferrs

Inferrs — це кастомний backend /v1, сумісний з OpenAI, тому той самий API локальної служби працює із записом провайдера 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,            },          },        ],      },    },  },}

Замініть command на результат which inferrs на машині, де запущено OmeniaClaw.

Приклад 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: [],      },    },  },}

Операційні нотатки

• Один процес OmeniaClaw керує дочірнім процесом, який він запустив. Інший процес OmeniaClaw, який бачить, що той самий URL перевірки вже активний, повторно використає його без переймання керування.
• Запуск серіалізується для кожної команди провайдера та набору аргументів, тому паралельні запити не створюють дублікати серверів для тієї самої конфігурації.
• Активні streaming-відповіді утримують lease; вимкнення через простій чекає, доки обробка тіла відповіді завершиться.
• Використовуйте timeoutSeconds для повільних локальних провайдерів, щоб холодні запуски й довгі генерації не впиралися в типовий timeout запиту до моделі.
• Використовуйте явний healthUrl, якщо ваш сервер надає готовність десь іще, крім /v1/models.

Пов’язане