ارائه‌دهنده llama.cpp

llama-cpp، Plugin رسمی ارائه‌دهندهٔ خارجی برای تعبیه‌سازی‌های محلی GGUF است. این Plugin شناسهٔ ارائه‌دهندهٔ تعبیه‌سازی local را ثبت می‌کند و مالک وابستگی زمان اجرای node-llama-cpp است که توسط memorySearch.provider: "local" استفاده می‌شود.

پیش از استفاده از تعبیه‌سازی‌های محلی حافظه، آن را نصب کنید:

openclaw plugins install @openclaw/llama-cpp-provider

بستهٔ اصلی openclaw در npm شامل node-llama-cpp نیست. نگه‌داشتن این وابستگی بومی در این Plugin مانع از آن می‌شود که به‌روزرسانی‌های عادی OpenClaw از طریق npm، زمان اجرایی را که به‌صورت دستی در پوشهٔ بستهٔ OpenClaw نصب شده است حذف کنند.

پیکربندی

مقدار memorySearch.provider را روی local تنظیم کنید:

{  agents: {    defaults: {      memorySearch: {        provider: "local",        local: {          modelPath: "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",        },      },    },  },}

مقدار پیش‌فرض local.modelPath همان URI با پیشوند hf: است که در بالا نمایش داده شده (embeddinggemma-300m-qat-Q8_0.gguf). برای استفاده از مدلی دیگر، آن را به یک URI متفاوت با پیشوند hf: یا یک فایل محلی .gguf ارجاع دهید. local.modelCacheDir محل ذخیرهٔ موقت مدل‌های دانلودشده را بازنویسی می‌کند (پیش‌فرض: ~/.node-llama-cpp/models) و local.contextSize یک عدد صحیح یا "auto" می‌پذیرد.

وقتی local.contextSize عددی باشد، ارائه‌دهنده این نیازمندی را نیز به جانمایی خودکار لایه‌های GPU در node-llama-cpp می‌دهد. این کار به node-llama-cpp اجازه می‌دهد مدل و زمینهٔ تعبیه‌سازی را با هم جای دهد و در عین حال بررسی‌های ایمنی حافظهٔ خود را حفظ کند. با "auto"، node-llama-cpp جانمایی خودکار عادی خود را حفظ می‌کند.

زمان اجرای بومی

برای روان‌ترین مسیر نصب بومی، از Node 24 استفاده کنید. درخت‌های منبعی که از pnpm استفاده می‌کنند ممکن است نیاز داشته باشند وابستگی بومی را تأیید و دوباره بسازند:

pnpm approve-buildspnpm rebuild node-llama-cpp

عیب‌یابی زمان اجرا

پس از بارگذاری ارائه‌دهنده، openclaw memory status --deep را اجرا کنید تا پشتیبان و ساخت منتخب، نام دستگاه‌ها، لایه‌های واگذارشده به GPU، اندازهٔ زمینهٔ درخواستی و آخرین نمای لحظه‌ای مشاهده‌شده از VRAM یا حافظهٔ یکپارچه را بررسی کنید. مقادیر VRAM شامل برچسب زمانی مشاهده هستند، زیرا خواندن‌های غیرفعال وضعیت، مدل را دوباره بارگذاری نمی‌کنند و دستگاه را پایش دوره‌ای نمی‌کنند.

همین اطلاعاتِ آخرین وضعیت شناخته‌شده ممکن است در openclaw doctor نیز ظاهر شوند، مشروط بر اینکه Gateway در حال اجرا قبلاً از ارائه‌دهندهٔ محلی استفاده کرده باشد. فرمان عادی وضعیت یا doctor صرفاً برای جمع‌آوری اطلاعات عیب‌یابی، مدلی را بارگذاری نمی‌کند.

رفع اشکال

اگر node-llama-cpp موجود نباشد یا بارگذاری آن ناموفق باشد، OpenClaw خطا را همراه با این راهکارها گزارش می‌کند:

1. Plugin را نصب کنید: openclaw plugins install @openclaw/llama-cpp-provider.
2. برای نصب‌ها و به‌روزرسانی‌های بومی از Node 24 استفاده کنید.
3. در یک درخت منبع pnpm: ابتدا pnpm approve-builds و سپس pnpm rebuild node-llama-cpp را اجرا کنید.

برای استفادهٔ آسان‌تر از تعبیه‌سازی‌های محلی بدون مرحلهٔ ساخت بومی، به‌جای آن memorySearch.provider را روی یک ارائه‌دهندهٔ تعبیه‌سازی راه‌دور مانند lmstudio، ollama، openai یا voyage تنظیم کنید.