Referencia de la CLI local de Foundry

Importante

La CLI local de Foundry está disponible en versión preliminar. Las versiones preliminares públicas proporcionan un acceso temprano a las funciones que se encuentran en la implementación activa.
Las características, los enfoques y los procesos pueden cambiar o tener funcionalidades limitadas, antes de la disponibilidad general (GA).

En este artículo se proporciona una referencia completa para la interfaz de la línea de comandos local (CLI) de Foundry. La CLI organiza los comandos en categorías lógicas para ayudarle a administrar modelos, controlar el servidor local y mantener la memoria caché local.

Prerequisites

Instale Foundry Local.
Terminal local donde la foundry CLI está disponible.
Asegúrese de tener acceso a Internet para las descargas iniciales (proveedores de ejecución y modelos).
Azure RBAC: no aplicable (se ejecuta localmente).
Si tiene una NPU de Intel en Windows, instale el controlador NPU de Intel para obtener una aceleración óptima de NPU.

Instalación de Foundry Local

Instale Foundry Local mediante el administrador de paquetes para el sistema operativo.

Windows: abra un terminal y ejecute:
```
winget install Microsoft.FoundryLocal
```
macOS: abra un terminal y ejecute:
```
brew tap microsoft/foundrylocal
brew install foundrylocal
```
Como alternativa, descargue el instalador del repositorio foundry-samples GitHub.

Compruebe la instalación:

foundry --version

Asegúrese de que tiene derechos de administrador para instalar software.

Tip

Si ve un error de conexión de servicio después de la instalación (por ejemplo, Request to local service failed), ejecute foundry server restart.

Comprobación rápida

Ejecute estos comandos para confirmar que la CLI está instalada y el servicio es accesible.

Mostrar ayuda de la CLI:
```
 foundry --help
```
Este comando imprime información de uso y la lista de grupos de comandos disponibles.

Referencia: Información general
Compruebe el estado del servidor:

estado del servidor encontrado '''

Este comando imprime si el demonio local de Foundry se está ejecutando e incluye su punto de conexión local.

Referencia: Comandos del servidor

Visión general

Use la ayuda integrada para explorar comandos y opciones.

La CLI organiza los comandos en los grupos siguientes:

Modelo: model, cache
Ejecutar: run, chat, complete, , transcribe
Servidor: server
Configuración: config
Ayuda: status, report

En la tabla siguiente se resumen los comandos de nivel superior:

Command	Descripción
`foundry model`	Detecta, inspecciona, descarga, carga y descarga modelos locales.
`foundry chat <model>`	Inicia una sesión de chat local interactiva.
`foundry complete <model> <prompt>`	Genera una finalización de texto sin estado.
`foundry run <model>`	Ejecuta un modelo con enrutamiento automático a chat o transcripción.
`foundry server`	Inicia, detiene, reinicia, inspecciona y soluciona los problemas del demonio de Foundry local.
`foundry cache`	Inspecciona y administra las entradas de caché del modelo descargadas.
`foundry config`	Visualiza y edita la configuración persistente de la CLI de Foundry.
`foundry status`	Muestra diagnósticos de sistema, servicio, modelo y conectividad.
`foundry report`	Abre un problema de GitHub rellenado previamente con diagnósticos.
`foundry transcribe`	Inicia una sesión interactiva de transcripción de voz local o transcribe un archivo.

Comandos de modelo

En la tabla siguiente se resumen los comandos relacionados con la administración y ejecución de modelos:

Note

Puede especificar el model argumento por su alias o identificador de modelo. Uso de un alias:

Selecciona el mejor modelo para el hardware disponible automáticamente. Por ejemplo, si tiene una GPU de Nvidia disponible, Foundry Local selecciona el mejor modelo de GPU. Si tiene una NPU compatible disponible, Foundry Local selecciona el modelo de NPU.
Permite usar un nombre más corto sin necesidad de recordar el identificador del modelo.

Si desea ejecutar un modelo específico, use el identificador del modelo. Por ejemplo, para ejecutar en la qwen2.5-0.5b CPU, independientemente del hardware disponible, use foundry run qwen2.5-0.5b-instruct-generic-cpu.

Command	Descripción
`foundry model --help`	Muestra todos los comandos disponibles relacionados con el modelo y su uso.
`foundry model list`	Enumera todos los modelos disponibles para su uso local. En la primera ejecución, descarga proveedores de servicios de ejecución (EPs) para tu hardware.
`foundry model info <model>`	Muestra información detallada sobre un modelo específico.
`foundry model download <model>`	Descarga un modelo en la caché local sin ejecutarlo.
`foundry model load <model>`	Carga un modelo en el servicio.
`foundry model unload <model>`	Descarga un modelo del servicio.

Ordenación de listas de modelos

Cuando hay varias variantes de identificador de modelo disponibles para un alias, la lista de modelos muestra los modelos en orden de prioridad. El primer modelo de la lista es el modelo que se ejecuta al especificar el modelo por alias.

Filtrado de lista de modelos

Use las opciones explícitas para foundry model list restringir o expandir los resultados.

Note

Cuando se ejecuta foundry model list por primera vez después de la instalación, Foundry Local descarga automáticamente los proveedores de ejecución (EPs) pertinentes para la configuración de hardware de la máquina. Verá una barra de progreso que indica la finalización de la descarga antes de que aparezca la lista de modelos.

Opción	Descripción
`--device <device>`	Filtra los modelos por dispositivo.
`--type <type>`	Filtra los modelos por tipo.
`--search <query>`	Filtra los modelos por una consulta de búsqueda.
`--cached`	Filtra la lista para los modelos almacenados en caché.
`--loaded`	Filtra la lista para cargar modelos.
`--variants`	Incluye variantes de modelo en la lista.

Ejemplos

foundry model list --device gpu
foundry model list --type chat
foundry model list --search qwen
foundry model list --cached
foundry model list --loaded
foundry model list --variants

Estos ejemplos filtran o expanden la lista de modelos mediante las opciones admitidas.

Referencia: filtrado de lista de modelos

Ejecutar un modelo de forma interactiva

Ejecute un modelo e interactúe directamente con él en el terminal:

foundry chat qwen2.5-0.5b

Foundry Local descarga el modelo en la primera ejecución y, a continuación, inicia una sesión interactiva. Escriba un mensaje para obtener una respuesta:

Why is the sky blue?

Tip

Reemplace por qwen2.5-0.5b cualquier alias de modelo del catálogo. Ejecute foundry model list para ver los modelos disponibles. Foundry Local descarga la variante que mejor coincide con el hardware( por ejemplo, una variante CUDA para GPU NVIDIA o una variante de NPU para NPUs Qualcomm.

Comandos de servidor.

En la tabla siguiente se resumen los comandos relacionados con la administración y ejecución del servicio local foundry:

Command	Descripción
`foundry server --help`	Muestra todos los comandos disponibles relacionados con el servidor y su uso.
`foundry server start`	Inicia el demonio local de Foundry y el servicio local compatible con OpenAI.
`foundry server start --port <port>`	Inicia el servicio local en el puerto TCP especificado. Se usa `0` para un puerto asignado por el sistema operativo.
`foundry server start --idle-timeout <minutes>`	Detiene el demonio después del número especificado de minutos inactivos. Use `0` para mantener el demonio en ejecución.
`foundry server stop`	Detiene el demonio local de Foundry.
`foundry server restart`	Reinicia el demonio local de Foundry y el servicio local.
`foundry server restart --port <port> --idle-timeout 0`	Reinicia el servicio local en el puerto TCP especificado y mantiene el demonio en ejecución.
`foundry server status`	Muestra el estado del demonio, las direcciones URL del servicio local, el identificador de proceso, el tiempo de actividad y la ubicación del registro.
`foundry server logs`	Muestra los registros de demonio local y SDK de Foundry.

Servidor local de puerto fijo

Para iniciar el servicio local en un puerto fijo y mantener el demonio en ejecución, use --port con --idle-timeout 0:

foundry server start --port 39839 --idle-timeout 0

Si el demonio ya se está ejecutando y necesita aplicar un puerto nuevo, reinícielo con las mismas opciones:

foundry server restart --port 39839 --idle-timeout 0

Para comprobar la dirección URL del punto de conexión local, ejecute:

foundry server status

Comandos de caché

En la tabla siguiente se resumen los comandos para administrar la caché local donde se almacenan los modelos:

Command	Descripción
`foundry cache --help`	Muestra todos los comandos relacionados con la caché disponibles y su uso.
`foundry cache location`	Muestra el directorio de caché actual.
`foundry cache list`	Enumera todos los modelos almacenados en la caché local.
`foundry cache cd <path>`	Cambia el directorio de caché a la ruta de acceso especificada.
`foundry cache remove <model>`	Elimina un modelo de la caché local.

Proveedores de ejecución

Los proveedores de ejecución son bibliotecas de aceleración específicas del hardware que ejecutan modelos lo más eficientemente posible en el dispositivo.

Proveedores de ejecución integrados

Foundry Local incluye el proveedor de ejecución de CPU, el proveedor de ejecución de WebGPU y el proveedor de ejecución CUDA.

El proveedor de ejecución de CPU usa Microsoft subrutinas de álgebra lineal (MLAS) para ejecutarse en cualquier CPU y es la reserva de CPU para Foundry Local.

El proveedor de ejecución de WebGPU utiliza Dawn, la implementación nativa de la API basada en la web, para la aceleración con cualquier GPU, y es la alternativa de GPU para Foundry Local.

El proveedor de ejecución CUDA utiliza NVIDIA CUDA para la aceleración en las GPU NVIDIA. Requiere una serie NVIDIA GeForce RTX 30 y versiones posteriores con una versión mínima recomendada del controlador 32.0.15.5585 y CUDA versión 12.5. Está sujeto a los siguientes términos de licencia: Contrato de licencia para kits de desarrollo de software de NVIDIA: CLUF.

Proveedores de ejecución de complementos

Los proveedores de ejecución enumerados en la tabla siguiente están disponibles para la descarga dinámica y el registro en Windows, en función de la compatibilidad del dispositivo y del controlador. Están sujetos a los términos de licencia especificados.

Foundry Local descarga automáticamente estos proveedores de ejecución en la primera ejecución. Los proveedores de ejecución de complementos se actualizan automáticamente cuando hay nuevas versiones disponibles.

Nombre (proveedor)	Requisitos	Términos de licencia
`NvTensorRTRTXExecutionProvider` (NVIDIA)	NVIDIA GeForce RTX 30XX y versiones posteriores con la versión mínima recomendada del controlador 32.0.15.5585 y CUDA versión 12.5	Contrato de licencia para kits de desarrollo de software de NVIDIA: CLUF
`OpenVINOExecutionProvider` (Intel)	CPU: Intel TigerLake (11ª generación) y versiones posteriores con el controlador recomendado mínimo 32.0.100.9565 GPU: Intel AlderLake (12ª generación) y versiones posteriores con el controlador recomendado mínimo 32.0.101.1029 NPU: Intel ArrowLake (15ª generación) y versiones posteriores con el controlador recomendado mínimo 32.0.100.4239	Contrato de licencia de uso comercial de distribución de Intel OBL v2025.02.12
`QNNExecutionProvider` (Qualcomm)	Snapdragon(R) X Elite - X1Exxxxx - NPU Qualcomm(R) Hexagon(TM) con versión mínima del controlador 30.0.140.0 y versiones posteriores Snapdragon(R) X Plus - X1Pxxxxx - Qualcomm(R) Hexagon(TM) NPU con la versión mínima del controlador 30.0.140.0 y versiones posteriores	Para ver la licencia de QNN, descargue el SDK de procesamiento neuronal de Qualcomm®, extraiga el archivo ZIP y abra el archivo LICENSE.pdf.
`VitisAIExecutionProvider` (AMD)	Min: Adrenalin Edition 25.6.3 con el controlador NPU 32.00.0203.280 Max: Adrenalin Edition 25.9.1 con el controlador NPU 32.00.0203.297	No se requiere ninguna licencia adicional

Uso de Open WebUI con el servidor local

Conecte Open WebUI a Foundry Local para una interfaz de chat basada en explorador que se ejecute completamente en el dispositivo.

Inicie un modelo y deje abierto el terminal:

foundry run qwen2.5-0.5b


1. Get your local endpoint URL:

```bash
foundry server status

Copie la dirección URL del punto de conexión. Foundry Local asigna un puerto dinámico cada vez que se inicia el servicio.

Instale e inicie Open WebUI y, a continuación, abra http://localhost:8080 en el explorador.
Conexión de Open WebUI a Foundry Local:
1. Vaya a Configuración Conexiones de configuración>>y habilite Conexiones directas.
2. Vaya a Configuración>Conexiones>administrar conexiones directas y seleccione +.
3. Establezca la dirección URL en http://localhost:PORT/v1 (reemplace por PORT el puerto del paso 2) y Autenticación en Ninguno.
4. Haga clic en Guardar.
Seleccione un modelo en la lista desplegable y empiece a chatear.

Tip

Si no aparecen modelos, ejecute foundry run <model> en un terminal y vuelva a cargar Open WebUI. Si se produce un error en la conexión, confirme el puerto con foundry server status.

Actualizar Foundry Local

Ejecute el comando para que el sistema operativo actualice Foundry Local.

Windows:

winget upgrade --id Microsoft.FoundryLocal

macOS:
```
brew upgrade foundrylocal
```

Desinstalación local de Foundry

Ejecute el comando para que el sistema operativo desinstale Foundry Local.

Windows:

winget uninstall Microsoft.FoundryLocal

macOS:

brew rm foundrylocal
brew untap microsoft/foundrylocal
brew cleanup --scrub

Solución de problemas

Problemas de conexión de servicio

Si ve este error al ejecutar un comando como foundry model list:

Exception: Request to local service failed.
Uri: http://127.0.0.1:0/foundry/list

The requested address is not valid in its context. (127.0.0.1:0)

Please check service status with 'foundry server status'.

Reinicie el servicio :

foundry server restart

Este comando corrige los casos en los que el servidor se ejecuta, pero no es accesible debido a un problema de enlace de puerto.

Para obtener más instrucciones de solución de problemas, consulte Procedimientos recomendados y solución de problemas.

Comentaris

Us ha resultat útil aquesta pàgina?

Last updated on 2026-08-05