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,взаимодействует с локальными моделями.
Настройка 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 Coder | 7B / 14B / 32B | 8G / 16G / 32G | Общее программирование, многоязычность |
| DeepSeek Coder V2 | 16B / 236B | 16G / 128G+ | Сложные задачи программирования |
| CodeLlama | 7B / 13B / 34B | 8G / 16G / 32G | Автодополнение кода, общее программирование |
| Mistral | 7B | 8G | Лёгкий помощник для программирования |
Способность локальных моделей к программированию обычно слабее, чем у лучших облачных моделей (таких как 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.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 для быстрого переключения между двумя моделями.