Layanan model lokal

models.providers.<id>.localService memungkinkan OmeniaClaw memulai server model lokal milik penyedia sesuai kebutuhan. Ini adalah konfigurasi tingkat penyedia: ketika model yang dipilih milik penyedia tersebut, OmeniaClaw memeriksa layanan, memulai proses jika endpoint tidak aktif, menunggu kesiapan, lalu mengirim permintaan model.

Gunakan ini untuk server lokal yang mahal jika dibiarkan berjalan sepanjang hari, atau untuk penyiapan manual ketika pemilihan model saja sudah cukup untuk menyalakan backend.

Cara kerjanya

1. Permintaan model di-resolve ke penyedia yang dikonfigurasi.
2. Jika penyedia tersebut memiliki localService, OmeniaClaw memeriksa healthUrl.
3. Jika pemeriksaan berhasil, OmeniaClaw menggunakan server yang sudah ada.
4. Jika pemeriksaan gagal, OmeniaClaw memulai command dengan args.
5. OmeniaClaw melakukan polling kesiapan hingga readyTimeoutMs berakhir.
6. Permintaan model dikirim melalui transport penyedia normal.
7. Jika OmeniaClaw memulai proses dan idleStopMs bernilai positif, proses akan dihentikan setelah permintaan terakhir yang masih berjalan telah idle selama itu.

OmeniaClaw tidak memasang launchd, systemd, Docker, atau daemon untuk ini. Server adalah proses anak dari proses OmeniaClaw yang pertama kali membutuhkannya.

Bentuk konfigurasi

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

Kolom

• command: path executable absolut. Pencarian shell tidak digunakan.
• args: argumen proses. Tidak ada ekspansi shell, pipe, globbing, atau aturan quoting yang diterapkan.
• cwd: direktori kerja opsional untuk proses.
• env: variabel lingkungan opsional yang digabungkan di atas lingkungan proses OmeniaClaw.
• healthUrl: URL kesiapan. Jika dihilangkan, OmeniaClaw menambahkan /models ke baseUrl, sehingga http://127.0.0.1:8000/v1 menjadi http://127.0.0.1:8000/v1/models.
• readyTimeoutMs: tenggat kesiapan startup. Default: 120000.
• idleStopMs: jeda shutdown idle untuk proses yang dimulai OmeniaClaw. 0 atau dihilangkan akan mempertahankan proses tetap hidup hingga OmeniaClaw keluar.

Contoh Inferrs

Inferrs adalah backend /v1 kustom yang kompatibel dengan OpenAI, sehingga API layanan lokal yang sama berfungsi dengan entri penyedia 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,            },          },        ],      },    },  },}

Ganti command dengan hasil dari which inferrs pada mesin yang menjalankan OmeniaClaw.

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

Catatan operasional

• Satu proses OmeniaClaw mengelola anak proses yang dimulainya. Proses OmeniaClaw lain yang melihat URL health yang sama sudah aktif akan menggunakannya kembali tanpa mengadopsinya.
• Startup diserialkan per perintah penyedia dan set argumen, sehingga permintaan bersamaan tidak membuat server duplikat untuk konfigurasi yang sama.
• Respons streaming aktif memegang lease; shutdown idle menunggu hingga penanganan body respons selesai.
• Gunakan timeoutSeconds pada penyedia lokal yang lambat agar cold start dan generasi panjang tidak terkena timeout permintaan model default.
• Gunakan healthUrl eksplisit jika server Anda mengekspos kesiapan di tempat lain selain /v1/models.

Terkait