Pi Agent y modelos locales con llama.cpp

Pi Agent incluye soporte integrado para llama.cpp, lo que te permite ejecutar grandes modelos de código abierto localmente, sin necesidad de una API en la nube.


¿Qué es llama.cpp?

llama.cpp es un motor de inferencia de LLM de alto rendimiento que puede ejecutar grandes modelos de lenguaje de código abierto en hardware de consumo.

Admite inferencia por CPU (reduciendo significativamente los requisitos de memoria mediante técnicas de cuantización) y aceleración por GPU (CUDA, Metal, Vulkan, etc.).

Pi Agent a través delservidor enrutador llama.cppse comunica con los modelos locales.

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


Configurar llama.cpp

La configuración consta de tres pasos: primero iniciar el enrutador llama-server, luego registrar el proveedor de llama.cpp y finalmente cargar y seleccionar el modelo.

Iniciar el enrutador llama-server

Sin-mo--modelparámetros al iniciar llama-server, se entra en modo enrutador.

Una vez que se pasa el parámetro de modelo, llama-server entra en modo de modelo único y ya no escanea el directorio de modelos.

El enrutador carga o descarga bajo demanda--models-dirlos modelos GGUF en el directorio. Los parámetros comunes son --models-dir (directorio de modelos), --no-models-autoload (desactivar carga automática), --jinja (habilitar soporte para plantillas de conversación y llamadas a herramientas), -ngl (número de capas descargadas a la GPU) y -c 32768 (ventana de contexto de cada modelo).

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

Después de iniciarlo, puedes usar los endpoints /health y /models para comprobar si el enrutador es accesible y si se han detectado los modelos.

Iniciar sesión en llama.cpp

En el modo interactivo de Pi Agent:

/login llama.cpp

Este paso solo registra el proveedor local; no requiere autenticación de cuenta, pero debes completar la dirección del enrutador (por defecto http://127.0.0.1:8080).

Al ejecutarlo, Pi te pedirá que completes la URL del enrutador y una API Key opcional. En los servicios locales normalmente puedes dejar la API Key vacía.

Gestionar modelos locales

Usa/llamael comando para abrir el menú de gestión de modelos:

/llama

En el menú, selecciona un modelo no cargado y pulsa Enter para cargarlo en memoria.

Si seleccionas un modelo ya cargado y pulsas Enter, se descargará de la memoria.

Selecciona el elemento del menúDownload model...Puedes buscar en Hugging Face y descargar nuevos modelos. Durante la carga o descarga, puedes presionar Escape para confirmar la cancelación.

El menú siempre muestra el estado real actual del enrutador, y solo los modelos cargados aparecen en el selector /model.

Cambiar a un modelo local

Usa/modelel comando para seleccionar un modelo local cargado.

En cuanto a los atajos de teclado, Ctrl+L abre el selector de modelos y Ctrl+P alterna cíclicamente entre modelos.


Modelos de código abierto recomendados

A continuación se presentan algunos modelos de código abierto adecuados para ejecutarse localmente:

ModeloParámetrosVRAM/RAM mínimaCasos de uso
Qwen 2.5 Coder7B / 14B / 32B8G / 16G / 32GCodificación general, multilingüe
DeepSeek Coder V216B / 236B16G / 128G+Tareas de programación complejas
CodeLlama7B / 13B / 34B8G / 16G / 32GAutocompletado de código, codificación general
Mistral7B8GAsistente de codificación ligero

La capacidad de codificación de los modelos locales suele ser inferior a la de los mejores modelos en la nube (como Claude Sonnet, GPT-4o), pero son una muy buena alternativa en escenarios con redes restringidas, altos requisitos de sensibilidad de datos o cuando se necesita un uso frecuente.


Almacenamiento de modelos

El directorio de modelos está determinado por el parámetro de inicio de llama-server--models-dir(por ejemplo, ~/models), y la descarga de modelos también la ejecuta el servidor llama.cpp.

Los archivos de modelo suelen ser grandes (de varios GB a decenas de GB). Asegúrate de que el directorio tenga suficiente espacio en disco.


Personalizar el servidor llama.cpp

Si tu servidor llama.cpp se ejecuta en un puerto no predeterminado o en una máquina remota, hay dos formas de conectarse.

El método sin código consiste en configurar la variable de entornoLLAMA_BASE_URLyLLAMA_API_KEYpara apuntar a un servidor llama.cpp personalizado, sin necesidad de escribir extensiones ni usar /login.

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

Si el servidor tiene habilitada una API Key, al iniciar llama-server debes incluir el mismo valor de --api-key y mantener --host 127.0.0.1 para restringir el acceso a la máquina local.

Cuando solo necesitas conectarte a una API compatible con OpenAI, el método de models.json es más sencillo; consulta el capítulo "Conexión con DeepSeek". Solo utiliza el método de extensión cuando necesites control total sobre el flujo de solicitudes.

Registrar el proveedor de llama.cpp en una extensión:

Ejemplo

// Ruta del archivo: ~/.pi/agent/extensions/llamacpp-provider.ts
pi.registerProvider("llama.cpp", {
  name: "llama.cpp local",
  baseUrl: "http://localhost:8080/v1",
  apiKey: "local",
  api: "openai-completions",
  // Descubrir dinámicamente los modelos cargados
  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"],
      cost: {
        input: 0,
        output: 0,
        cacheRead: 0,
        cacheWrite: 0,
      },
      contextWindow: 128000,
      maxTokens: 16384,
    }));
  },
});

Este modo de descubrimiento dinámico permite que Pi Agent obtenga en tiempo real la lista de modelos actualmente cargados en el servidor llama.cpp.

Guarda el archivo en el directorio ~/.pi/agent/extensions/ y reinicia Pi Agent; la extensión se cargará automáticamente y registrará este proveedor.

Una vez activado, abre el selector /model y podrás ver los modelos actualmente cargados en el servidor llama.cpp y conversar directamente.


Limitaciones de los modelos locales

Al usar modelos locales, ten en cuenta los siguientes puntos:

  • Capacidad de llamada a herramientas: la capacidad de llamada a herramientas (tool calling) de algunos modelos de código abierto es débil y puede que no utilicen correctamente las herramientas integradas de Pi Agent.
  • Velocidad de inferencia: sin aceleración por GPU, la velocidad de inferencia puede ser lenta.
  • Longitud de contexto: la ventana de contexto efectiva de los modelos locales suele ser menor que la de los modelos en la nube.
  • Nivel de razonamiento: los modelos no razonadores siempre se ejecutan en off y no pueden utilizar la función de nivel de razonamiento.

Cuando la capacidad de llamada a herramientas es débil, la manifestación más común es que el modelo trata la llamada a herramientas como una salida de texto, en lugar de activar realmente la herramienta.

> 查看 src/index.ts 的内容

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

Si no aparece una tarjeta de llamada a herramientas en el área de mensajes, significa que el modelo no está llamando realmente a la herramienta read, sino que está inventando el contenido del archivo.

Ante esta situación, puedes cambiar a un modelo con mejor soporte de llamada a herramientas o dividir la tarea en pasos más pequeños.

Estrategia híbrida recomendada: usa modelos en la nube (como Claude Sonnet) cuando necesites razonamiento profundo y codificación compleja, y cambia a modelos locales para tareas simples diarias o cuando la red esté restringida.

Usa Ctrl+P para cambiar rápidamente entre los dos modelos.

Otras extensiones