Pi Agent et les modèles locaux llama.cpp

Pi Agent dispose d'une prise en charge intégrée de llama.cpp, ce qui vous permet d'exécuter localement des grands modèles open source sans API cloud.


Qu'est-ce que llama.cpp

llama.cpp est un moteur d'inférence LLM haute performance capable d'exécuter des grands modèles de langage open source sur du matériel grand public.

Il prend en charge l'inférence CPU (réduisant drastiquement les besoins en mémoire via la quantification) et l'accélération GPU (CUDA, Metal, Vulkan, etc.).

Pi Agent, via leserveur routeur llama.cpp,communique avec des modèles locaux.

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


Configurer llama.cpp

La configuration implique trois étapes : d'abord démarrer le routeur llama-server, puis enregistrer le fournisseur llama.cpp, et enfin charger et sélectionner un modèle.

Démarrer le routeur llama-server

Sans-mou--modelparamètres, le démarrage de llama-server entrera en mode routeur.

Une fois qu'un paramètre de modèle est passé, llama-server entre en mode modèle unique et ne parcourt plus le répertoire des modèles.

Le routeur chargera ou déchargera à la demande--models-dirles modèles GGUF dans le répertoire. Les paramètres courants incluent --models-dir (répertoire des modèles), --no-models-autoload (désactiver le chargement automatique), --jinja (activer les gabarits de conversation et la prise en charge des appels d'outils), -ngl (nombre de couches déchargées vers le GPU), et -c 32768 (fenêtre de contexte par modèle).

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

Après le démarrage, vous pouvez utiliser les points de terminaison /health et /models pour vérifier si le routeur est joignable et si des modèles sont découverts.

Se connecter à llama.cpp

En mode interactif de Pi Agent :

/login llama.cpp

Cette étape enregistre uniquement le fournisseur local ; aucune authentification de compte n'est requise, mais vous devez renseigner l'adresse du routeur (par défaut http://127.0.0.1:8080).

Après l'exécution, Pi demandera l'URL du routeur et une clé API facultative. Pour les services locaux, vous pouvez généralement laisser la clé API vide.

Gérer les modèles locaux

Utilisez la commande/llamapour ouvrir le menu de gestion des modèles :

/llama

Dans le menu, sélectionnez un modèle non chargé et appuyez sur Entrée pour le charger en mémoire.

Sélectionnez un modèle chargé et appuyez sur Entrée pour le décharger.

Sélectionnez l'élément de menuTélécharger le modèle...pour rechercher sur Hugging Face et télécharger de nouveaux modèles. Pendant le chargement ou le téléchargement, appuyez sur Échap pour confirmer l'annulation.

Le menu affiche toujours l'état réel actuel du routeur, et seuls les modèles chargés apparaissent dans le sélecteur /model.

Passer à un modèle local

Utilisez la commande/modelpour sélectionner un modèle local chargé.

Raccourcis clavier : Ctrl+L ouvre le sélecteur de modèle, Ctrl+P fait défiler les modèles.


Modèles open source recommandés

Voici quelques modèles de codage open source adaptés à une exécution locale :

ModèleParametersVRAM/RAM minimaleCas d'utilisation
Qwen 2.5 Coder7B / 14B / 32B8G / 16G / 32GCodage général, multilingue
DeepSeek Coder V216B / 236B16G / 128G+Tâches de programmation complexes
CodeLlama7B / 13B / 34B8G / 16G / 32GComplétion de code, codage général
Mistral7B8GAssistant de codage léger

La capacité de codage des modèles locaux est généralement plus faible que celle des meilleurs modèles cloud (tels que Claude Sonnet, GPT-4o), mais ils constituent une très bonne alternative dans les scénarios où le réseau est restreint, où les exigences de sensibilité des données sont élevées ou en cas d'utilisation fréquente.


Stockage des modèles

Le répertoire des modèles est déterminé par le paramètre de démarrage de llama-server--models-dir(comme ~/models) ; les téléchargements de modèles sont également exécutés par le serveur llama.cpp.

Les fichiers de modèle sont généralement volumineux (de quelques GB à des dizaines de GB). Veuillez vous assurer que le répertoire dispose de suffisamment d'espace disque.


Serveur llama.cpp personnalisé

Si votre serveur llama.cpp s'exécute sur un port non par défaut ou sur une machine distante, il existe deux façons de se connecter.

L'approche sans code consiste à définir la variable d'environnementLLAMA_BASE_URLetLLAMA_API_KEYpour pointer vers un serveur llama.cpp personnalisé ; pas besoin d'écrire des extensions ni d'utiliser /login.

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

Si le serveur a une clé API activée, llama-server doit être démarré avec la même valeur --api-key, et conservez --host 127.0.0.1 pour restreindre l'accès à la machine locale.

Lorsque vous avez uniquement besoin de vous connecter à une API compatible OpenAI, l'approche models.json est plus simple ; consultez le chapitre « Connexion à DeepSeek ». Utilisez l'approche par extension lorsque vous avez besoin d'un contrôle total sur le flux de requêtes.

Enregistrez le fournisseur llama.cpp dans une extension :

Exemple

// Chemin du fichier : ~/.pi/agent/extensions/llamacpp-provider.ts
pi.registerProvider("llama.cpp", {
  name: "llama.cpp local",
  baseUrl: "http://localhost:8080/v1",
  apiKey: "local",
  api: "openai-completions",
  // Découvrir dynamiquement les modèles chargés
  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"],
      coût: {
        input: 0,
        output: 0,
        cacheRead: 0,
        cacheWrite: 0,
      },
      contextWindow: 128000,
      maxTokens: 16384,
    }));
  },
});

Ce mode de découverte dynamique permet à Pi Agent d'obtenir la liste des modèles actuellement chargés sur le serveur llama.cpp en temps réel.

Enregistrez le fichier dans le répertoire ~/.pi/agent/extensions/ et redémarrez Pi Agent ; l'extension se chargera automatiquement et enregistrera ce fournisseur.

Une fois qu'il a pris effet, ouvrez le sélecteur /model pour voir les modèles actuellement chargés sur le serveur llama.cpp et discutez directement avec eux.


Limites des modèles locaux

Lors de l'utilisation de modèles locaux, tenez compte des points suivants :

  • Capacité d'appel d'outils: certains modèles open source ont une faible capacité d'appel d'outils et peuvent ne pas utiliser correctement les outils intégrés de Pi Agent
  • Vitesse d'inférence: sans accélération GPU, la vitesse d'inférence peut être plus lente.
  • Longueur de contexte: la fenêtre de contexte effective des modèles locaux est généralement plus petite que celle des modèles cloud.
  • Niveau de raisonnement: les modèles sans raisonnement s'exécutent toujours en mode off et ne peuvent pas utiliser la fonctionnalité de niveau de raisonnement.

Lorsque la capacité d'appel d'outils est faible, le symptôme le plus courant est que le modèle affiche l'appel d'outil sous forme de texte au lieu de déclencher réellement l'outil.

> 查看 src/index.ts 的内容

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

Si aucune carte d'appel d'outil n'apparaît dans la zone de message, cela signifie que le modèle n'a pas réellement appelé l'outil read, mais qu'il a fabriqué lui-même le contenu du fichier.

Dans ce cas, vous pouvez passer à un modèle offrant une meilleure prise en charge de l'appel d'outils, ou décomposer la tâche en étapes plus petites.

Stratégie hybride recommandée : utilisez des modèles cloud (comme Claude Sonnet) lorsqu'un raisonnement approfondi et un codage complexe sont nécessaires, et passez à des modèles locaux pour les tâches simples de routine ou lorsque le réseau est restreint.

Utilisez Ctrl+P pour basculer rapidement entre deux modèles.

Autres extensions