Manual completo de comandos de Ollama
Este capítulo presenta los comandos de ejecución relacionados con Ollama, incluyendo instalación, gestión de modelos, parámetros de ejecución, Modelfile, API REST, variables de entorno y resolución de problemas comunes, todo basado en Ollama 0.17.x.
Instalación y arranque
En las tres plataformas hay un método de instalación estándar. Una vez instalado, Ollama se ejecuta automáticamente como servicio en segundo plano y escucha en127.0.0.1:11434。
| Plataforma | Método de instalación | Descripción |
|---|---|---|
| macOS | brew install ollama | También se puede descargar el paquete de instalación dmg desde el sitio web oficial |
| Linux | curl -fsSL https://ollama.com/install.sh | sh | Script oficial de un clic, configura automáticamente el servicio systemd |
| Windows | Descargar el paquete de instalación desde el sitio web oficial | Instalar mediante el asistente, se registra automáticamente como servicio del sistema |
| Docker | docker run -d -v ollama:/root/.ollama -p 11434:11434 ollama/ollama | Volumen de datos: Ollama guarda los modelos de forma persistente |
En la mayoría de los casos no es necesario iniciar el servicio manualmente, pero se utiliza para solucionar problemas y cambiar temporalmente la configuración.ollama serve。
Ejemplo
ollama serve
# Verifica si el servicio está listo: si devuelve "Ollama is running", todo es normal
curl http://localhost:11434
Si indica que el puerto está ocupado, significa que el servicio en segundo plano ya está en ejecución. En este caso, ejecutar `ollama serve` en otra terminal dará un error, lo cual es normal; simplemente use la línea de comandos o la API.
Tabla completa de comandos de gestión de modelos
La gestión de modelos es la parte principal de la línea de comandos de Ollama; hay alrededor de diez comandos, todos listados en la siguiente tabla.
| Comando | Función | Ejemplo |
|---|---|---|
| ollama pull <model> | Descarga un modelo desde el repositorio de modelos; si no se especifica una etiqueta, por defecto se obtiene `latest` | ollama pull qwen3.5:4b |
| ollama run <model> | Ejecuta un modelo de forma interactiva; si no está local, lo descarga automáticamente | ollama run qwen3.5 |
| ollama list / ollama ls | Lista los modelos locales, su tamaño y fecha de modificación | ollama list |
| ollama show <model> | Muestra los detalles del modelo: parámetros, plantilla, aviso del sistema, etc. | ollama show qwen3.5 |
| ollama ps | Muestra los modelos cargados en memoria y el tiempo de vida restante | ollama ps |
| ollama stop <model> | Detiene y descarga inmediatamente el modelo en ejecución | ollama stop qwen3.5 |
| ollama cp <src> <dst> | Copia o renombra un modelo | ollama cp qwen3.5 ejemplo-clone |
| ollama rm <model> | Elimina un modelo local y libera espacio en disco | ollama rm qwen3.5:0.8b |
| ollama create <name> -f <file> | Crea un modelo personalizado basado en un Modelfile | ollama create ejemplo-coder -f Modelfile |
| ollama push <model> | Envía el modelo a un repositorio remoto; requiere iniciar sesión primero | ollama push myteam/ejemplo-coder |
| ollama serve | Inicia el servicio en segundo plano, normalmente se ejecuta automáticamente con el sistema | ollama serve |
La combinación de mayor uso diario son los cuatro comandos `run`, `list`, `ps` y `rm`: ejecutar modelos, revisar el inventario, ver la memoria y liberar espacio.
Ejemplo
ollama pull qwen3.5:0.8b
# Crea una copia y cambia su nombre
ollama cp qwen3.5 ejemplo-clone
# Después de confirmar que la copia se hizo correctamente, elimina la especificación que ya no se necesita
ollama rm qwen3.5:0.8b
`rm` elimina el archivo de modelo correspondiente a esa etiqueta. Si otras etiquetas comparten los mismos pesos subyacentes (blobs), el espacio en disco solo se libera realmente cuando se elimina la última etiqueta que lo referencie.
El comando run y el modo interactivo
`run` funciona tanto como herramienta de preguntas y respuestas de una sola vez, como para entrar en modo interactivo de conversación de múltiples turnos, y también admite cambiar parámetros en tiempo de ejecución.
Parámetros de línea de comandos
Los parámetros se escriben después del nombre del modelo, solo afectan a la ejecución actual y no se guardan en la configuración del modelo.
Ejemplo
ollama run qwen3.5
# Pregunta y respuesta única: el aviso sigue al nombre del modelo, y sale automáticamente después de responder
ollama run qwen3.5 "Presenta ejemplo (Tutorial para novatos) en una frase"
# Muestra estadísticas de tokens: tiempo total, tokens por segundo y otras métricas de rendimiento
ollama run qwen3.5 --verbose
# Fuerza al modelo a generar salida en formato JSON
ollama run qwen3.5 --format json
# Aumenta la ventana de contexto (en tokens)
ollama run qwen3.5 --num-ctx 8192
# Intenta colocar la mayor cantidad posible de capas del modelo en la GPU (999 significa sin límite)
ollama run qwen3.5 --num-gpu 999
Comandos de barra diagonal dentro del modo interactivo
Después de entrar en el modo interactivo, los comandos que comienzan con barra diagonal se usan para ajustar el estado de la sesión; estos ajustes solo afectan a la sesión actual.
| Comando | Función |
|---|---|
| /set parameter <name> <value> | Ajusta temporalmente los parámetros de inferencia, como `temperature` |
| /set system <prompt> | Establece temporalmente el aviso del sistema |
| /show info | Muestra información del modelo actual |
| /show modelfile | Muestra el Modelfile correspondiente al modelo actual |
| /save <name> | Guarda la configuración de la sesión actual como un nuevo modelo |
| /load <name> | Carga un modelo o sesión guardados |
| /clear | Limpia el contexto de la conversación actual y comienza de nuevo |
| /bye | Sale del modo interactivo |
Si quieres conservar a largo plazo los parámetros ajustados con los comandos de barra diagonal, usa `/save` para guardarlos como un nuevo modelo; detrás de esto se genera un Modelfile.
Otra forma rápida de salir del modo interactivo es presionar Ctrl+D, que tiene el mismo efecto que `/bye`.
Modelos personalizados con Modelfile
Modelfile utiliza una sintaxis similar a Dockerfile para empaquetar "modelo base + parámetros + aviso del sistema" en un nuevo modelo.
Ejemplo
# FROM especifica el modelo base (obligatorio), también puede ser la ruta de un archivo GGUF local
FROM qwen3.5
# Parámetros de inferencia comunes (opcionales)
PARAMETER temperature 0.2
PARAMETER num_ctx 8192
# Aviso del sistema, determina el rol y comportamiento del modelo (opcional)
SYSTEM Eres un ingeniero de Python senior, genera código conciso, tipado y comprobable.
Ejemplo
ollama create ejemplo-coder -f Modelfile
# Ejecuta como un modelo normal
ollama run ejemplo-coder "Escribe un quicksort, con pruebas"
Para importar pesos GGUF locales solo necesitas apuntar `FROM` a la ruta del archivo; se usa a menudo para ejecutar archivos de modelo descargados de la comunidad de código abierto.
Ejemplo
# FROM apunta al archivo de pesos GGUF local
FROM ./model-file.gguf
Todas las directivas de Modelfile se muestran en la siguiente tabla; las tres primeras líneas son la combinación más utilizada.
| Directiva | Efecto | ¿Obligatorio? |
|---|---|---|
| FROM | Especifica el modelo base o la ruta de archivo GGUF | Obligatorio |
| PARAMETER | Establece parámetros de inferencia: `temperature`, `num_ctx`, `top_p`, `stop`, etc. | Opcional |
| SYSTEM | Establece el aviso del sistema | Opcional |
| TEMPLATE | Personaliza la plantilla de aviso de conversación | Opcional |
| ADAPTER | Carga adaptadores LoRA | Opcional |
| MESSAGE | Proporciona ejemplos de conversación predefinidos para guiar con pocos ejemplos (few-shot) | Opcional |
| LICENSE | Declara la licencia del modelo | Opcional |
Si quieres modificar un modelo existente sin empezar desde cero, primero ejecutaollama show --modelfile 模型名exporta la receta completa, modifícala y luego ejecuta `create`.
Referencia rápida de la API REST
Después de iniciar el servicio de Ollama, escucha por defecto enhttp://localhost:11434, todo lo que puede hacer la CLI también lo puede hacer la API.
| Endpoint | Método | Función |
|---|---|---|
| /api/generate | POST | Generación de texto de un solo turno, retorno en streaming por defecto |
| /api/chat | POST | Conversación de múltiples turnos, pasa el historial mediante el arreglo `messages` |
| /api/embed | POST | Genera incrustaciones (embeddings) de texto para su uso en recuperación RAG |
| /api/tags | GET | Lista los modelos locales, corresponde a `ollama list` |
| /api/show | POST | Muestra los detalles del modelo, corresponde a `ollama show` |
| /api/pull | POST | Descarga un modelo, corresponde a `ollama pull` |
| /api/delete | DELETE | Elimina un modelo, corresponde a `ollama rm` |
Ejemplo
curl http://localhost:11434/api/generate -d '{
"model": "qwen3.5",
"prompt": "Escribe un Hola Mundo en Python"
}'
# Conversación de múltiples turnos
curl http://localhost:11434/api/chat -d '{
"model": "qwen3.5",
"messages": [{"role": "user", "content": "Explica qué es una API REST"}]
}'
# Genera incrustaciones vectoriales
curl http://localhost:11434/api/embed -d '{
"model": "nomic-embed-text",
"input": "El contenido de tu texto"
}'
# Lista los modelos locales
curl http://localhost:11434/api/tags
# Muestra los detalles del modelo
curl http://localhost:11434/api/show -d '{"model": "qwen3.5"}'
# Elimina un modelo
curl -X DELETE http://localhost:11434/api/delete -d '{"model": "qwen3.5"}'
Interfaz compatible con OpenAI
Ollama proporciona un endpoint compatible con OpenAI/v1/chat/completionsEl código existente del ecosistema OpenAI se puede usar directamente apuntando base_url a local.
Ejemplo
from openai import OpenAI
# base_url apunta a Ollama local; api_key puede ser cualquier cadena no vacía
client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
model="qwen3.5", # Nombre del modelo descargado localmente
messages=[{"role": "user", "content": "Hola, por favor cuéntame sobre ejemplo"}],
)
print(resp.choices[0].message.content)
$ python3 openai_compat.py 你好!ejemplo(Ejemplo)是一个面向初学者的编程学习网站,提供大量免费的基础技术教程。
Referencia rápida de variables de entorno
Las variables de entorno son la forma principal de configurar el comportamiento del servicio Ollama. Después de cambiarlas, es necesario reiniciar el servicio para que surtan efecto.
| Variable | Descripción | valor por defecto |
|---|---|---|
| OLLAMA_HOST | Dirección de escucha del servicio; 0.0.0.0 indica que se permite el acceso desde la red de área local. | 127.0.0.1:11434 |
| OLLAMA_MODELS | Ruta de almacenamiento de modelos, útil al cambiar a un disco más grande. | ~/.ollama/models |
| OLLAMA_NUM_GPU | Número de capas del modelo que se colocan en la GPU; 999 significa todas. | automático |
| OLLAMA_NUM_PARALLEL | Número de solicitudes concurrentes para el mismo modelo. | automático |
| OLLAMA_MAX_LOADED_MODELS | Número máximo de modelos que permanecen en memoria al mismo tiempo. | automático |
| OLLAMA_FLASH_ATTENTION | Habilitar Flash Attention; se recomienda activarlo para contextos largos. | Cerrar |
| OLLAMA_KEEP_ALIVE | Tiempo de inactividad del modelo antes de descargarlo de la memoria. | 5m |
| OLLAMA_DEBUG | Activar registros de depuración para mostrar información de ejecución más detallada. | Cerrar |
Ejemplo
export OLLAMA_HOST=0.0.0.0:11434
export OLLAMA_MODELS=/data/ollama-models
ollama serve
Establecer OLLAMA_KEEP_ALIVE en 0 significa que el modelo se descarga inmediatamente después de cada solicitud, ahorrando memoria pero requiriendo recargar el modelo en cada solicitud; para mantenerlo residente, establézcalo en -1. El formato de este valor varía según la versión; consulte ollama serve --help y la documentación oficial.
Solución de problemas comunes
Cuando encuentre una anomalía, primero consulte la siguiente tabla para identificarla. La mayoría de los problemas pertenecen a tres categorías: "nombre del modelo incorrecto, servicio no iniciado, recursos insuficientes".
| problema | Ideas de solución de problemas |
|---|---|
| VRAM / RAM insuficiente (OOM). | Cambie a una especificación de modelo más pequeña o a una precisión de cuantización más baja, por ejemplo, use 4b en lugar de 9b. |
| Aviso: model not found | Verifique que el nombre del modelo y la etiqueta sean correctos. La etiqueta se separa con dos puntos, como qwen3.5:4b en lugar de qwen3.5-4b. |
| connection refused | Confirmar si el servicio está en ejecución y comprobar si el puerto 11434 está ocupado. |
| Velocidad de respuesta lenta | Usa `ollama ps` para revisar la columna PROCESSOR y confirma si el modelo realmente se ejecuta en la GPU; reduce adecuadamente el valor de num_ctx. |
| Ofuscación de modelos de múltiples versiones | Si no se especifica el tag, se elegirá la versión "más reciente" según las reglas internas; se recomienda indicar siempre explícitamente el tag completo. |
Tabla de referencia rápida en una frase
Finalmente, se condensan los comandos de mayor frecuencia en una tabla, lista para copiar y usar.
| comando | función |
|---|---|
| ollama pull <model> | Descargar modelo |
| ollama run <model> | Ejecutar modelo / Entrar en diálogo interactivo |
| ollama list | Ver los modelos descargados. |
| ollama show <model> | Ver detalles del modelo |
| ollama ps | Ver modelos en ejecución |
| ollama stop <model> | Detener y desinstalar el modelo |
| ollama rm <model> | Eliminar modelo |
| ollama cp <old> <new> | Copiar / Renombrar modelo |
| ollama create <name> -f Modelfile | Utilice Modelfile para crear modelos personalizados. |
| ollama serve | Iniciar servicio |
Otras extensionesOllama se actualiza rápidamente; algunos parámetros y comportamientos de comandos pueden variar según la versión. Antes de actuar, consulte `ollama --help` y la documentación oficial.