Pi Agent и локальные модели llama.cpp

Pi Agent имеет встроенную поддержку llama.cpp, позволяя запускать открытые большие модели локально без облачных API.


Что такое llama.cpp

llama.cpp — это высокопроизводительный движок вывода LLM, который может запускать открытые большие языковые модели на потребительском оборудовании.

Он поддерживает вывод на CPU (резко снижая требования к памяти за счёт квантования) и ускорение на GPU (CUDA, Metal, Vulkan и т. д.).

Pi Agent черезllama.cpp router server,взаимодействует с локальными моделями.

Pi Agent 与 llama.cpp 路由器、本地模型文件的链路示意,以及可选的云端路径


Настройка llama.cpp

Настройка состоит из трёх шагов: сначала запустите роутер llama-server, затем зарегистрируйте провайдер llama.cpp и, наконец, загрузите и выберите модель.

Запуск роутера llama-server

Без-mили--modelпараметров запуск llama-server перейдёт в режим роутера.

Как только передан параметр модели, llama-server переходит в режим одной модели и больше не сканирует каталог моделей.

Роутер будет загружать или выгружать по требованию--models-dirGGUF-модели в каталоге. Обычные параметры включают --models-dir (каталог моделей), --no-models-autoload (отключить автозагрузку), --jinja (включить шаблоны разговоров и поддержку вызова инструментов), -ngl (число слоёв, выгружаемых на GPU) и -c 32768 (окно контекста на модель).

llama-server \
  --models-dir ~/models \
  --no-models-autoload \
  --jinja \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl 999 \
  -c 32768

После запуска можно использовать эндпоинты /health и /models, чтобы проверить, доступен ли роутер и обнаружены ли модели.

Вход в llama.cpp

В интерактивном режиме Pi Agent:

/login llama.cpp

Этот шаг только регистрирует локального провайдера; аутентификация учетной записи не требуется, но необходимо указать адрес роутера (по умолчанию http://127.0.0.1:8080).

После выполнения Pi запросит URL роутера и необязательный API-ключ. Для локальных сервисов обычно можно оставить API-ключ пустым.

Управление локальными моделями

Используйте команду/llama, чтобы открыть меню управления моделями:

/llama

В меню выберите незагруженную модель и нажмите Enter, чтобы загрузить её в память.

Выберите загруженную модель и нажмите Enter, чтобы выгрузить её.

Выберите пункт менюСкачать модель..., чтобы найти модели на Hugging Face и скачать новые. Во время загрузки или скачивания нажмите Escape, чтобы подтвердить отмену.

Меню всегда показывает реальное текущее состояние роутера, и только загруженные модели отображаются в селекторе /model.

Переключиться на локальную модель

Используйте команду/model, чтобы выбрать загруженную локальную модель.

Горячие клавиши: Ctrl+L открывает селектор моделей, Ctrl+P переключает между моделями.


Рекомендуемые модели с открытым исходным кодом

Вот несколько открытых моделей для программирования, подходящих для локального запуска:

МодельParametersМинимальные требования к VRAM/RAMСценарии использования
Qwen 2.5 Coder7B / 14B / 32B8G / 16G / 32GОбщее программирование, многоязычность
DeepSeek Coder V216B / 236B16G / 128G+Сложные задачи программирования
CodeLlama7B / 13B / 34B8G / 16G / 32GАвтодополнение кода, общее программирование
Mistral7B8GЛёгкий помощник для программирования

Способность локальных моделей к программированию обычно слабее, чем у лучших облачных моделей (таких как Claude Sonnet, GPT-4o), но они являются очень хорошей альтернативой в сценариях с ограниченными сетями, высокими требованиями к чувствительности данных или частым использованием.


Хранилище моделей

Каталог моделей определяется стартовым параметром llama-server--models-dir(например, ~/models); загрузка моделей также выполняется сервером llama.cpp.

Файлы моделей обычно большие (от нескольких GB до десятков GB). Пожалуйста, убедитесь, что в каталоге достаточно места на диске.


Пользовательский сервер llama.cpp

Если ваш сервер llama.cpp работает на нестандартном порту или на удалённой машине, есть два способа подключиться.

Подход без кода — задать переменные средыLLAMA_BASE_URLиLLAMA_API_KEY, указывающие на пользовательский сервер llama.cpp; не нужно писать расширения или использовать /login.

export LLAMA_BASE_URL=http://192.168.1.20:8080
export LLAMA_API_KEY=optional-secret
pi

Если на сервере включён API-ключ, llama-server необходимо запустить с тем же значением --api-key и оставить --host 127.0.0.1, чтобы ограничить доступ локальной машиной.

Когда вам нужно только подключиться к API, совместимому с OpenAI, подход с models.json проще; см. главу «Подключение к DeepSeek». Используйте подход с расширением, когда нужен полный контроль над потоком запросов.

Зарегистрируйте провайдера llama.cpp в расширении:

Пример

// Путь к файлу: ~/.pi/agent/extensions/llamacpp-provider.ts
pi.registerProvider("llama.cpp", {
  name: "Local llama.cpp",
  baseUrl: "http://localhost:8080/v1",
  apiKey: "local",
  api: "openai-completions",
  // Динамическое обнаружение загруженных моделей
  async refreshModels({ signal }) {
    const response = await fetch(
      "http://localhost:8080/v1/models",
      { signal }
    );
    const { data } = await response.json();
    return data.map(({ id }) => ({
      id,
      name: id,
      reasoning: false,
      input: ["text"],
      стоимость: {
        input: 0,
        output: 0,
        cacheRead: 0,
        cacheWrite: 0,
      },
      contextWindow: 128000,
      maxTokens: 16384,
    }));
  },
});

Этот режим динамического обнаружения позволяет Pi Agent получать в реальном времени список моделей, загруженных в данный момент на сервере llama.cpp.

Сохраните файл в каталог ~/.pi/agent/extensions/ и перезапустите Pi Agent; расширение автоматически загрузится и зарегистрирует этого провайдера.

После того как это вступит в силу, откройте селектор /model, чтобы увидеть модели, загруженные на сервере llama.cpp, и общаться с ними напрямую.


Ограничения локальных моделей

При использовании локальных моделей учитывайте следующее:

  • Способность вызывать инструменты: некоторые open-source модели имеют слабые способности к вызову инструментов и могут неправильно использовать встроенные инструменты Pi Agent
  • Скорость инференса: без ускорения GPU скорость инференса может быть ниже.
  • Длина контекста: эффективное окно контекста локальных моделей обычно меньше, чем у облачных моделей.
  • Уровень рассуждений: модели без поддержки рассуждений всегда работают в режиме off и не могут использовать функцию уровня рассуждений.

Если способность вызывать инструменты слаба, наиболее частый симптом — модель выводит вызов инструмента как текст, вместо того чтобы фактически запустить инструмент.

> 查看 src/index.ts 的内容

好的,下面是 src/index.ts 的内容:
import { createAgent } from "pi";
export const agent = createAgent();
...

Если в области сообщений не появляется карточка вызова инструмента, это означает, что модель на самом деле не вызвала инструмент read, а вместо этого сама выдумала содержимое файла.

В этом случае можно переключиться на модель с лучшей поддержкой вызова инструментов или разбить задачу на более мелкие шаги.

Рекомендуемая гибридная стратегия: используйте облачные модели (например, Claude Sonnet), когда требуется глубокое рассуждение и сложное программирование, и переключайтесь на локальные модели для обычных простых задач или когда доступ к сети ограничен.

Используйте Ctrl+P для быстрого переключения между двумя моделями.

Другие расширения