- Los flujos de trabajo de FreeToken local api comienzan con la instalación de la aplicación de escritorio oficial o de la CLI.
- Ruta compatible: Windows y Linux son los entornos de escritorio documentados para la versión actual.
- Propósito principal: Ejecutar modelos grandes de Mixture-of-Experts utilizando GPU, CPU y memoria del sistema.
- Buena práctica: Confirma la API oficial o el comando de servicio antes de escribir integraciones para clientes.
- Limitación principal: macOS, las tarjetas NVIDIA antiguas y varios backends solicitados podrían requerir compatibilidad futura.
Descripción general de FreeToken local api
FreeToken local api se refiere al uso de FreeToken como servicio de inferencia local en lugar de depender de un endpoint de modelos alojado. FreeToken es un motor de servicio de Mixture-of-Experts nativo para el edge, diseñado para ejecutar modelos de pesos abiertos a escala de frontera en hardware de consumo. Su arquitectura documentada combina la memoria de la GPU, los recursos de la CPU, la memoria del sistema y la interconexión disponible en una única plataforma de inferencia.
La ventaja práctica es la flexibilidad. Los modelos MoE pueden contener cientos de miles de millones de parámetros y activar únicamente un grupo más pequeño de expertos para cada token. FreeToken se centra en mover y almacenar en caché esos expertos de forma eficiente, en lugar de asumir que todos los pesos del modelo deben permanecer en la memoria de la GPU en todo momento.
Aspectos destacados del video:
- FreeToken está orientado al servicio local de modelos MoE grandes en hardware personal.
- El motor da prioridad al almacenamiento en caché de expertos basado en el enrutamiento y a la coordinación entre CPU y GPU.
- Los benchmarks publicados deben considerarse benchmarks del proyecto hasta que se reproduzcan de forma independiente.
- La compatibilidad de hardware sigue siendo más limitada que la de los runtimes consolidados con múltiples backends.
El repositorio oficial de FreeToken en GitHub identifica el proyecto como software bajo la licencia Apache 2.0. También incluye una aplicación de escritorio para Windows y Linux, además de instalación mediante CLI a través de uv o pip. Esto hace que el proyecto sea adecuado para experimentación local, investigación y flujos de trabajo con agentes, pero los usuarios deben distinguir el motor de inferencia de una API HTTP garantizada.
| Área | Lo que proporciona FreeToken | Significado práctico |
|---|---|---|
| Arquitectura del modelo | Servicio de Mixture-of-Experts | Los modelos grandes pueden distribuir el trabajo entre los recursos disponibles |
| Estrategia de memoria | Caché global de expertos LRU | Los expertos usados con frecuencia pueden permanecer disponibles para tokens posteriores |
| Ejecución | Coejecución de CPU y GPU | El trabajo puede adaptarse al ancho de banda y al equilibrio del hardware |
| Gestión del estado | Puntos de control de anclaje semántico | El trabajo repetido con el contexto puede reducirse durante las ediciones agénticas |
| Licencia | Licencia Apache 2.0 | Adecuada para revisión, modificación e investigación conforme a la licencia |
Considera “local API” como un objetivo de integración, no como una prueba de la existencia de un endpoint específico. Utiliza la documentación actual de instalación y servicio del proyecto para identificar la interfaz compatible con tu versión.
Aplicación de escritorio
Una ruta de configuración gráfica para usuarios de Windows y Linux que desean seleccionar modelos, chatear y ajustar el motor desde una sola interfaz.
Flujo de trabajo con CLI
Una ruta basada en terminal que utiliza la instalación documentada del paquete de Python o una copia del código fuente.
Runtime MoE
El motor principal coordina la ubicación de los expertos entre la GPU, la CPU, la memoria del sistema y los recursos de interconexión.
Capa de investigación
Los pesos FTW, el almacenamiento en caché semántico y la ejecución compatible con grafos están orientados a casos de uso avanzados de inferencia local.
Instalación y primer lanzamiento
La configuración más sencilla depende de si deseas un flujo de trabajo gráfico o un entorno de desarrollo repetible. El repositorio documenta tanto una aplicación de escritorio como una ruta mediante CLI. Windows y Linux son el foco actual, mientras que la compatibilidad con macOS no aparece como una compilación compatible en la información disponible del proyecto.
Antes de instalar, comprueba tu sistema operativo, la configuración de NVIDIA u otro acelerador compatible, la memoria del sistema y el formato del modelo. No asumas que un modelo compatible con otro runtime funcionará sin cambios en FreeToken.
Elige la ruta de instalación
Utiliza la descarga oficial para escritorio para realizar una configuración guiada en Windows o Linux. Elige la CLI cuando necesites scripts, entornos virtuales, cambios en el código fuente o comandos de desarrollo repetibles.
Instala el runtime
Para la ruta de paquetes documentada, crea o utiliza un entorno de Python e instala el extra para aceleradores con uv pip install "freetoken[accel]". Mantén el comando alineado con las instrucciones actuales del repositorio.
Prepara el modelo
Selecciona un modelo de pesos abiertos que coincida con la ruta de servicio compatible con FreeToken. Los modelos MoE grandes pueden requerir una cantidad considerable de memoria del sistema, incluso cuando solo un subconjunto de expertos está activo para cada token.
Inicia una sesión local
Inicia la aplicación de escritorio o el comando CLI documentado del proyecto. Confirma que el modelo se carga, que se detecta el acelerador y que un prompt corto produce resultados antes de crear un cliente externo.
Registra la configuración funcional
Guarda el nombre del modelo, la cuantización o el formato de los pesos, la configuración de memoria, el sistema operativo y la versión del runtime. Estos datos facilitan la reproducción de comparaciones de rendimiento posteriores.
El repositorio también proporciona una ruta de instalación desde el código fuente:
git clone <repository-url>
cd FreeToken
uv venv
source .venv/bin/activate
uv pip install -e ".[accel]"
Utiliza la URL exacta del repositorio y el comando de activación específico de la plataforma que aparecen en la documentación oficial al aplicar este flujo de trabajo. El fragmento de código fuente no establece un comando universal para un servidor HTTP, así que evita insertar un endpoint no verificado en scripts de producción.
| Opción de configuración | Más adecuada para | Requisito principal | Punto de atención |
|---|---|---|---|
| Aplicación de escritorio | Usuarios primerizos | Sistema Windows o Linux | Menor control sobre los detalles de desarrollo |
Instalación del paquete uv | Uso repetible mediante CLI | Entorno de Python y compatibilidad con aceleradores | Mantén documentada la versión del paquete |
| Instalación editable desde el código fuente | Desarrolladores e investigadores | Git, herramientas de Python y dependencias de compilación | Los cambios en el código fuente pueden afectar la estabilidad |
| Integración con un cliente externo | Agentes y aplicaciones | Una interfaz de servicio local documentada | Los detalles del endpoint pueden cambiar según la versión |
La información disponible del proyecto indica compatibilidad de escritorio con Windows y Linux, además de un entorno orientado a NVIDIA CUDA. No asumas que macOS, las generaciones antiguas de NVIDIA, Apple Silicon o las configuraciones de Docker con dos GPU son compatibles sin consultar la documentación oficial actual.
Creación de un flujo de trabajo local fiable
Una vez que FreeToken se inicie correctamente, construye tu flujo de trabajo de API local por capas. Primero valida la generación directa. Después confirma que la carga del modelo sea repetible. Solo entonces conecta un agente, un editor o un cliente personalizado. Este orden permite separar los problemas del modelo de los problemas de integración.
Un servicio local puede ser útil para agentes de programación porque las solicitudes permanecen en el hardware del usuario y no están sujetas a los límites de velocidad ni al calendario de retirada de modelos de un proveedor alojado. Estos beneficios no eliminan la necesidad de supervisar la memoria, la latencia, el tamaño del contexto y la estabilidad del proceso.
Utiliza este flujo de trabajo:
- Comienza con un prompt corto y un contexto moderado.
- Confirma que el modelo seleccionado responde de forma coherente en varias solicitudes.
- Aumenta gradualmente la longitud del contexto en lugar de probar de inmediato con el prompt más grande.
- Supervisa la memoria de la GPU, la memoria del sistema y la capacidad de respuesta del equipo.
- Añade llamadas a herramientas o bucles de agentes solo después de estabilizar la inferencia de un solo turno.
- Conserva una configuración alternativa para modelos más pequeños o contextos reducidos.
| Etapa del flujo de trabajo | Objetivo de validación | Acción recomendada |
|---|---|---|
| Generación directa | El modelo devuelve resultados coherentes | Prueba primero con prompts cortos |
| Solicitudes repetidas | El proceso sigue respondiendo | Ejecuta varios turnos sin cambiar la configuración |
| Crecimiento del contexto | El uso de memoria escala de forma aceptable | Aumenta la longitud del prompt en pasos medidos |
| Conexión del agente | El cliente recibe respuestas válidas | Utiliza la interfaz documentada para la versión instalada |
| Sesión prolongada | La caché y el estado permanecen estables | Supervisa la latencia de cola, la presión de memoria y las salidas del proceso |
El almacenamiento en caché con conocimiento semántico de FreeToken está diseñado para ediciones agénticas del contexto, incluidas las llamadas a herramientas y los bloques de razonamiento. El beneficio previsto es evitar el recálculo innecesario del contexto cuando una sesión cambia de forma estructurada. En la práctica, el comportamiento de la caché depende del modelo, el patrón de contexto, la memoria disponible y la configuración del runtime.
Mantén pequeña la primera integración: un modelo, un cliente, un formato de prompt y un equipo local. Amplíala con herramientas, solicitudes paralelas o agentes de larga duración solo después de que la ruta de solicitudes básica sea repetible.
Para las pruebas de rendimiento, mide algo más que los tokens por segundo. Registra:
- Tiempo hasta el primer token.
- Rendimiento de decodificación una vez iniciada la generación.
- Latencia máxima de un solo turno.
- Consumo de memoria durante el prellenado.
- Consumo de memoria durante la decodificación.
- Si el cliente o el supervisor terminan las solicitudes lentas.
Un promedio rápido puede ocultar un comportamiento inaceptable en la cola de latencia. Para un agente, una solicitud que ocasionalmente supera su tiempo de espera puede ser menos útil que una configuración más lenta que termine de forma fiable.
Rendimiento, almacenamiento en caché y elección del hardware
El diseño distintivo de FreeToken consiste en intentar que el hardware heterogéneo se comporte como una plataforma de inferencia elástica. El repositorio enumera la coejecución de CPU y GPU adaptada al ancho de banda, el streaming de prellenado con doble búfer, la caché global de expertos LRU, la ejecución compatible con grafos y el formato de pesos rápidos FTW.
El concepto más importante es la ubicación de los expertos. En un modelo MoE, solo los expertos seleccionados participan en el cálculo de cada token, pero los expertos disponibles deben seguir siendo accesibles cuando cambia el enrutamiento. Una caché puede reducir las transferencias repetidas de los expertos seleccionados con frecuencia, mientras que la ejecución entre CPU y GPU puede adaptarse al ancho de banda disponible en un equipo concreto.
| Función | Papel en el servicio | Efecto para el usuario |
|---|---|---|
| Caché global de expertos LRU | Conserva los expertos usados recientemente | Puede reducir el movimiento repetido de expertos |
| Ejecución adaptada al ancho de banda | Elige la cooperación entre CPU y GPU según los recursos | Ayuda a equilibrar los costes de cálculo y transferencia |
| Prellenado con doble búfer | Transmite capas completas durante el procesamiento del prompt | Busca una ingestión más fluida del prompt |
| Formato FTW | Proporciona una representación rápida de los pesos | Puede mejorar la carga o la ejecución en modelos compatibles |
| Puntos de control semánticos | Conserva estados recurrentes y KV útiles | Puede reducir el trabajo duplicado del contexto |
La selección del hardware debe comenzar por lo que ya tienes. Un sistema NVIDIA reciente con suficiente memoria del sistema es el objetivo más claro según el material disponible del proyecto. El motor no es un reemplazo universal de los runtimes maduros en todos los sistemas operativos y aceleradores.
Equipo de escritorio NVIDIA reciente
La opción más adecuada para probar el flujo de trabajo orientado a CUDA documentado y modelos MoE más grandes.
Memoria de GPU limitada
Elige los modelos con cuidado y espera que la memoria del sistema o la participación de la CPU tengan mayor importancia.
Plataforma no compatible
Consulta el rastreador oficial de incidencias y las notas de la versión antes de planificar una implementación de producción.
Al comparar FreeToken con otro runtime local, mantén la prueba en condiciones justas:
- Utiliza pesos de modelo idénticos y una cuantización comparable.
- Mantén constantes la longitud del prompt, el límite de salida y la configuración de muestreo.
- Separa la velocidad de prellenado de la velocidad de decodificación.
- Registra tanto la latencia mediana como la del peor caso.
- Repite las pruebas después de calentar la caché.
- Anota las versiones exactas del software y de los controladores.
La información disponible sobre benchmarks comunica resultados sólidos del propio proyecto en cargas de trabajo MoE seleccionadas, pero también subraya que no había benchmarks independientes disponibles en el momento de la revisión. Considera esas cifras como indicios útiles de orientación, no como una garantía universal.
Una comparación significativa de FreeToken debe incluir la latencia de cola y la compatibilidad del hardware. El rendimiento por sí solo no muestra si un agente de programación de larga duración terminará dentro de su tiempo de espera.
Solución de problemas y lista de preparación
La mayoría de los problemas del primer uso procede de una de cuatro áreas: hardware no compatible, instalación incompleta del acelerador, archivos de modelo inadecuados o una integración que da por hecho un endpoint no documentado. Resuélvelos en ese orden.
Si la instalación falla, vuelve a las instrucciones del repositorio oficial y confirma el entorno. Si la aplicación se inicia pero la generación falla, prueba con un modelo más pequeño o conocido como compatible antes de cambiar varias variables. Si la generación funciona pero un cliente no puede conectarse, consulta la documentación de servicio actual en lugar de adivinar rutas URL, puertos o esquemas de solicitud.
| Síntoma | Área probable | Primera respuesta |
|---|---|---|
| La instalación del paquete falla | Entorno o dependencia del acelerador | Recrea el entorno y revisa la ruta de instalación oficial |
| El modelo no se carga | Formato, memoria o compatibilidad | Prueba un modelo documentado y confirma la memoria disponible del sistema |
| La salida es extremadamente lenta | Presión de transferencia o fallos de caché | Reduce el contexto y supervisa la memoria de la GPU y del sistema |
| El cliente no puede conectarse | Desajuste de interfaz | Verifica las instrucciones de servicio local específicas de la versión |
| La sesión se detiene inesperadamente | Tiempo de espera o presión de recursos | Prueba solicitudes más cortas y registra la latencia del peor caso |
Lista de preparación para la API local:
- Instala FreeToken mediante la ruta oficial de escritorio o CLI
- Confirma que el acelerador y el sistema operativo sean compatibles
- Carga un modelo documentado y completa una prueba breve de generación
- Registra el modelo, el runtime, el controlador, la memoria y los detalles de configuración
- Verifica la interfaz de servicio actual antes de conectar un cliente externo
Utiliza la siguiente lista de comprobación de la versión antes de considerar fiable una configuración:
- Confirma la versión actual y la fecha de instalación en 2026.
- Guarda la URL del repositorio oficial y las notas de la versión.
- Prueba un inicio en frío y una solicitud con la caché calentada.
- Mide tanto el tiempo de respuesta normal como el del peor caso.
- Comprueba si el proceso sobrevive al prompt más largo previsto.
- Mantén disponible un modelo alternativo más pequeño.
- Evita exponer un servicio local fuera de tu red de confianza, a menos que estén documentadas medidas de autenticación y protección del transporte.
Un proceso de inferencia local aún puede exponer prompts sensibles si está vinculado a una interfaz de red accesible. Mantén los servicios de desarrollo restringidos a accesos de confianza, a menos que el proyecto documente controles de seguridad para implementaciones más amplias.
Q: ¿Para qué se utiliza FreeToken local api?
Se utiliza para crear flujos de trabajo de inferencia local alrededor de FreeToken, incluidos chats de escritorio, experimentos con CLI, herramientas de investigación e integraciones con agentes. La interfaz HTTP o de cliente exacta depende de la versión instalada y debe confirmarse en la documentación oficial.
Q: ¿FreeToken es compatible con Windows y Linux?
La información oficial disponible del proyecto documenta una aplicación de escritorio para Windows y Linux. El entorno indicado se centra en NVIDIA CUDA y POSIX Linux, así que debes verificar los detalles actuales de compatibilidad antes de utilizar otra plataforma.
Q: ¿Puede FreeToken ejecutar modelos MoE grandes en hardware de consumo?
FreeToken está diseñado para servir modelos MoE de pesos abiertos a escala de frontera utilizando recursos de GPU, CPU, memoria del sistema e interconexión. La compatibilidad real del modelo depende de la memoria disponible, el ancho de banda del hardware, los formatos compatibles y la versión actual del proyecto.
Q: ¿Dónde puedo encontrar la información oficial de instalación?
Utiliza el repositorio oficial de FreeToken en GitHub: https://github.com/FlashML-org/FreeToken. Allí se documentan la ruta de escritorio, la instalación del paquete, la configuración desde el código fuente, el resumen de funciones, la licencia y los enlaces del proyecto.