Needle Cactus Compute: Un Pequeño Modelo de Function Calling en IA

Una publicación sobre un modelo open-source de 26 millones de parámetros ha estado circulando en LinkedIn: Needle, de Cactus Compute, destilado a partir de Gemini para function calling en teléfonos y wearables. Es un proyecto realmente interesante, pero el repositorio ya ha avanzado más allá de esa versión. Cactus lanzó Needle 2 en los últimos días: 45 millones de parámetros, comprimidos en un único binario de 14MB, construido sobre una nueva receta de arquitectura que llaman Simple Attention Network. La idea central se mantiene y se vuelve más precisa: no es un chatbot más pequeño, es un tipo de modelo fundamentalmente distinto, uno que estructuralmente no puede producir una respuesta extensa en texto libre aunque quisieras que lo hiciera.

El error habitual al cubrir esta clase de modelo es tratarlo como “GPT pero pequeño”. No lo es, y las formas en que no lo es son precisamente las decisiones de ingeniería realmente interesantes: cada token que emite el modelo está restringido por una gramática compilada a partir de tus propios esquemas de funciones, cada respuesta lleva una puntuación de confianza calibrada sobre la que puedes actuar programáticamente, y una consulta fuera de tema no obtiene una respuesta inventada, sino una negativa explícita y estructurada. Esta publicación explica cómo se construye eso y cómo es realmente desarrollar sobre esa base.

Aprenderás:

• Por qué el tool calling es un problema fundamentalmente distinto de la generación abierta, y por qué eso permite que el modelo sea tan pequeño
• En qué se diferencia la arquitectura Simple Attention Network de Needle 2 de un transformer estándar
• Cómo la decodificación restringida por gramática a nivel de bytes garantiza una salida estructurada válida en lugar de simplemente esperarla
• Cómo funcionan el confidence gating y el tool retrieval, y por qué importan para la fiabilidad en producción
• Cómo hacer fine-tuning de Needle sobre tus propias herramientas con LoRA, y desplegar el resultado en el mismo motor ligero
• Las limitaciones reales de un modelo tan especializado, y dónde encaja frente a un LLM de propósito general

Tabla de contenidos

1. Conceptos básicos
2. La arquitectura completa
3. Capas principales explicadas
4. Recorrido completo de extremo a extremo
5. Casos especiales
6. Desafíos de escalado y producción
7. Ejemplos de código
8. Errores comunes
9. Buenas prácticas para producción

Conceptos básicos

Qué cubre realmente Needle

Needle resuelve exactamente un problema: dada una consulta y un conjunto de herramientas declaradas, decidir qué herramienta llamar y con qué argumentos rellenarla, o rechazar explícitamente si nada de lo declarado aplica. Ejecutar una acción y extraer datos estructurados de texto resultan ser la misma operación por debajo; la única diferencia es lo que declaras como la “herramienta”. Este es un alcance deliberadamente estrecho, y esa estrechez es precisamente el punto. El tool calling es fundamentalmente una tarea de recuperación y ensamblaje: emparejar una consulta con el nombre de una herramienta, extraer valores de argumentos de la entrada, emitir JSON válido; no razonamiento abierto. Un modelo construido específicamente para ese trabajo no necesita la enorme capacidad de conocimiento general que necesita un chatbot, y por eso precisamente 45 millones de parámetros, comprimidos en un binario de 14MB, pueden competir con modelos muchas veces mayores en esta tarea específica.

Por qué este es un problema de alto valor si se resuelve bien

• La IA en el dispositivo tiene restricciones reales que un modelo en la nube nunca tiene que cumplir. RAM medida en decenas de megabytes, sin conexión de red garantizada, y presupuestos de batería que hacen que un modelo de más de 1B parámetros sea inviable en un reloj o en unas gafas.
• Las funciones sensibles a la latencia no deberían recurrir a un LLM en la nube en absoluto. Un viaje de ida y vuelta a un modelo alojado para “apaga las luces” es tanto más lento como menos privado que un modelo que ya vive en el cliente y responde al instante.
• Las garantías estructurales importan más que la capacidad bruta para esta tarea. Un sistema de tool calling que ocasionalmente emite JSON malformado o alucina un parámetro no es solo incómodo: es una integración rota. Todo el diseño de Needle está construido para hacer estructuralmente imposible esa clase de fallo, en lugar de simplemente estadísticamente rara.

La arquitectura completa

Tool schemas ──▶ Grammar compiler (byte-level)
                         │
Query + schemas ──▶ Simple Attention Network ──▶ constrained decode ──▶ structured call
                                                                              │
                                                                       execute locally
                                                                              │
                                                                    result fed back in
                                                                              │
                                                                        next turn / final answer

El principio rector: los únicos grados de libertad del modelo son los que la gramática permite. La corrección se impone por construcción —una gramática a nivel de bytes compilada a partir de tus esquemas declarados restringe cada token durante la decodificación—, no confiando en que un modelo mucho más grande y mucho más lento se comporte bien por casualidad.

Capas principales explicadas

1. La arquitectura Simple Attention Network

Qué es: La receta de modelo pequeño denso de Needle 2, descrita en el propio paper de Cactus (arXiv:2607.18363). En lugar de un bloque feed-forward estándar, utiliza un MLP basado en la transformada de Hadamard, grouped-query attention, una memoria clave-valor “engram” construida a partir de tablas hash de n-gramas, e hyper-connections multi-carril que combinan varios flujos residuales. El enrutamiento entre componentes se normaliza mediante iteración de Sinkhorn en lugar de un simple softmax.

Por qué importa: Cada una de estas decisiones intercambia una parte de la “capacidad general” en la que un transformer estándar gasta parámetros por una eficiencia específica para esta tarea. El Needle original de 26M iba aún más lejos, usando atención pura y gating sin capas feed-forward en absoluto: una apuesta a que el tool calling no necesita el tipo de “almacenamiento de conocimiento” asociativo que normalmente proporciona un FFN. Needle 2 reintroduce un MLP ligero, pero deliberadamente barato, construido sobre una transformada de Hadamard fija y sin pesos en lugar de una matriz densa.

Consejo de producción: No esperes que esta arquitectura se generalice a una calidad de chat abierta: está optimizada específicamente para la forma de recuperación y ensamblaje del tool calling, y esa especialización es exactamente la razón por la que es lo bastante pequeña para ejecutarse en 28MB de RAM.

2. Decodificación restringida por gramática a nivel de bytes

Qué es: Cada esquema de herramienta que declaras se compila en una gramática que restringe qué tokens puede emitir el modelo en cada paso de decodificación. El modelo no puede producir JSON malformado, un nombre de herramienta no reconocido, ni un valor que viole una restricción declarada; no porque se le haya entrenado para no hacerlo, sino porque esos tokens inválidos simplemente no están disponibles durante la decodificación.

Por qué importa: Esto convierte “el modelo debería devolver JSON válido” de una esperanza probabilística en una garantía. Restricciones como rangos de valores, patrones regex, longitudes de cadena y enums —cualquier cosa expresable en el esquema— se compilan directamente en la gramática, así que un argumento fuera de los límites que declaraste literalmente no puede generarse.

Consejo de producción: Lleva la validación al esquema siempre que sea posible, en lugar de comprobarla después en el código de la aplicación. Un Literal["heat", "cool", "auto"] o un rango numérico declarado desde el principio significa que el modelo no puede emitir un valor inválido en primer lugar: no hay nada que capturar aguas abajo.

3. Confidence Gating

Qué es: Cada respuesta lleva una puntuación de confianza que es el mínimo de dos señales independientes: una cabeza calibrada que puntúa el prompt completo más la llamada producida, y la probabilidad bruta de decodificación de los tokens de la llamada. Ambas tienen que coincidir para obtener una puntuación alta.

Por qué importa: Esto te da un número único y fundamentado sobre el que construir una política real de escalado: actúa localmente por encima del umbral elegido, y vuelve a preguntar o deriva a un modelo en la nube más grande por debajo de él. El modo de fallo que esto está diseñado para producir es el escalado, no una ejecución silenciosamente incorrecta.

Consejo de producción: Ajusta el umbral por caso de uso, no globalmente; un interruptor de smart home puede tolerar un listón más bajo que algo como un pago o el envío de un mensaje, donde una llamada errónea y de baja confianza que se ejecute en silencio es un resultado mucho peor que volver a preguntar.

4. Tool Retrieval para catálogos grandes

Qué es: Con cinco herramientas declaradas o menos, todo se representa directamente en contexto. A partir de ahí, una cabeza de retrieval integrada embebe cada esquema de herramienta una sola vez, embebe la consulta en cada turno, y reduce el conjunto a las cinco herramientas con mayor puntuación, reconstruyendo la gramática de decodificación solo sobre ese subconjunto.

Por qué importa: Una herramienta no seleccionada no es solo poco probable que se llame: es realmente inalcanzable en ese turno, ya que la propia gramática solo permite el subconjunto recuperado. Esto es lo que permite que un dispositivo declare un gran catálogo de herramientas sin disparar el presupuesto de contexto ni ralentizar la decodificación intentando considerar todo en cada turno.

Consejo de producción: Persiste los embeddings de herramientas en disco en lugar de recomputarlos en cada sesión. Están indexados por una huella digital sobre el conjunto de esquemas y el modelo, así que un catálogo sin cambios se carga al instante y solo un esquema realmente modificado obliga a re-embeder.

5. Memoria acotada independientemente de la longitud de la conversación

Qué es: Una ventana deslizante de 256 tokens gestiona la conversación en curso, mientras que las herramientas declaradas permanecen fijadas en su sitio como “sumideros” clave-valor fijos en lugar de deslizarse fuera del contexto.

Por qué importa: El uso total de memoria se mantiene cerca de 28MB sin importar cuánto dure una conversación, un requisito estricto para cualquier cosa realmente desplegada en un wearable o dispositivo embebido, donde una memoria que crece sin límites con el uso simplemente no es viable.

6. Hechos del sistema, no instrucciones del sistema

Qué es: Un turno opcional del sistema transporta estado del entorno —fecha, locale, tipo de dispositivo, nivel de batería y claves reconocidas similares— estrictamente como hechos de los que el modelo puede razonar, nunca como instrucciones que dirijan su comportamiento.

Por qué importa: Esta es una decisión de diseño deliberadamente cercana a la seguridad. Como el modelo está entrenado para tratar este campo como datos y no como comandos, el texto colocado ahí no tiene oportunidad de anular o redirigir el comportamiento real del modelo, cerrando una clase de manipulación tipo prompt injection que un diseño de “system prompt” más permisivo dejaría abierta.

Consejo de producción: Resolver referencias temporales relativas (“mañana a las 7”) solo funciona cuando realmente se suministra un hecho date:; sin él, el modelo deja pasar la frase tal cual en lugar de adivinar una hora absoluta, que es el modo de fallo más seguro para cualquier cosa sensible al tiempo.

7. Fine-tuning con LoRA en un motor agnóstico a los pesos

Qué es: Needle hace fine-tuning con LoRA sobre un modelo base congelado, luego fusiona el adaptador y cuantiza el resultado en un único archivo .cact, un artefacto autocontenido que se ejecuta en exactamente el mismo motor de inferencia que el modelo base, sin requerir un paso de compilación separado.

Por qué importa: Esto hace que especializar el modelo en tu propio catálogo de herramientas sea realmente barato, y la salida sigue siendo tan simple de desplegar como la original: un archivo, un motor, sin recompilación.

Consejo de producción: Si aún no tienes ejemplos etiquetados, la cadena de herramientas puede sintetizar datos de entrenamiento directamente a partir de tus esquemas de herramientas mediante un paso de generación respaldado por OpenRouter; es una forma razonable de arrancar un primer fine-tuning antes de tener registros reales de uso de los que aprender.

Recorrido completo de extremo a extremo

Sigue una solicitud desde la consulta hasta la acción ejecutada:

1. Se declaran las herramientas, ya sea como funciones Python decoradas o como esquemas JSON en bruto; describiendo, por ejemplo, una herramienta set_lights con parámetros room, on y brightness.
2. El compilador de gramática construye una gramática de decodificación restringida a partir de esos esquemas en el momento en que se registran las herramientas.
3. Llega una consulta: “atenúa la sala de estar a 30”.
4. El modelo procesa la consulta frente a las herramientas declaradas y produce una llamada, con cada token restringido por la gramática compilada: es estructuralmente imposible que emita una llamada a una herramienta no declarada o un argumento malformado.
5. La respuesta incluye la propia llamada, una breve traza de razonamiento en lenguaje natural y una puntuación de confianza; algo como set_lights(room="living room", on=true, brightness=30) con alta confianza.
6. La confianza supera el umbral configurado, por lo que la llamada se ejecuta localmente sin escalado.
7. Para una tarea de varios pasos —por ejemplo, “envíale un mensaje a Alex diciendo que voy tarde”— el modelo primero llama a una herramienta search_for_contact, el resultado (un ID de contacto) se devuelve al siguiente turno, y el modelo luego llama a send_instant_message usando ese ID devuelto, encadenando llamadas como requiere un flujo de trabajo más largo.
8. Un turno final puede responder en texto plano una vez que se completan todas las llamadas necesarias, devuelto como un tipo distinto “respond” sin más llamadas de función adjuntas.

Casos especiales

La extracción es tool calling con una sola herramienta. Declarar un único esquema —una forma de registro como una factura o un recibo— y pasar texto donde iría una consulta devuelve los campos analizados como argumentos de ese esquema. Como solo se declara una herramienta, la gramática admite exactamente una llamada con ese nombre, por lo que la conformidad con el esquema está garantizada en lugar de ser solo probable.

Las consultas fuera de tema reciben una negativa estructurada, no una respuesta en texto libre. Si ninguna herramienta declarada puede atender una solicitud, el modelo devuelve una llamada vacía. No hay fallback a texto conversacional: ese es todo el contrato para manejar cualquier cosa fuera del alcance declarado, y es lo que mantiene predecible el comportamiento del modelo en una integración embebida.

Los argumentos opcionales se omiten, no se adivinan. Si la entrada no aporta evidencia para un campo opcional, se deja fuera de la llamada por completo en lugar de rellenarlo con una suposición plausible; la misma disciplina aplicada a los argumentos se aplica a las consultas completas fuera de tema.

Desafíos de escalado y producción

El fine-tuning a escala de flota aún tiene que encajar en la misma huella diminuta. Un adaptador LoRA se fusiona de nuevo en un único archivo .cact cuantizado, lo que significa que especializar el modelo por cliente, por clase de dispositivo o por catálogo de herramientas no multiplica tu complejidad de despliegue: cada variante sigue ejecutándose en el mismo motor ligero.

El ajuste del umbral de confianza es una decisión operativa continua, no una configuración única. A medida que tu catálogo de herramientas crece o los patrones de uso cambian, el umbral de escalado adecuado para una acción dada puede desplazarse; trátalo como una métrica que hay que monitorizar, no como una constante que se establece una vez y se olvida.

La calidad del retrieval importa más a medida que crece tu catálogo de herramientas. Más allá de cinco herramientas, la corrección depende de que la cabeza de retrieval realmente saque a la superficie las cinco candidatas correctas en cada turno; un catálogo con muchas herramientas casi duplicadas o mal descritas degradará la precisión del retrieval mucho antes de agotar la capacidad bruta del modelo.

Este es un especialista estrecho, y evaluarlo como un modelo generalista pierde el punto. Needle intercambia victorias con modelos enfocados en function calling muchas veces más grandes en precisión de tool-call de una sola pasada, pero esa comparación trata específicamente de tool calling, no de razonamiento general o conversación, y tomar benchmarks fuertes de function calling como evidencia de una capacidad más amplia sería un error.

Ejemplos de código

Declarar una herramienta con un decorador: la firma y el docstring por sí solos bastan para casos simples:

import needle

@needle.tool
def get_weather(city: str):
    "Get the current weather for a city."
    return {"city": city, "temp_c": 27, "sky": "clear"}

agent = needle.Needle(tools=[get_weather])
print(agent.run("what's it like in Lagos right now?"))

Añadir restricciones reales: rangos y patrones compilados directamente en la gramática de decodificación:

from typing import Annotated

@needle.tool
def send_money(
    amount: Annotated[float, needle.Field(gt=0, le=10000)],
    to: Annotated[str, needle.Field(pattern=r"^@[a-z0-9_]+$")],
):
    "Send money to a handle."
    return {"sent": amount, "to": to}

Extracción estructurada con un resultado tipado:

from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    total: float
    due_date: str

invoice = needle.extract("Invoice from Acme Corp, $1,200.00, due 2026-09-01", Invoice)

Fine-tuning de extremo a extremo sobre tus propias herramientas:

needle generate-data --tools my_tools.json --num-samples 500 --output data.jsonl
needle finetune data.jsonl --epochs 3
needle build checkpoints/needle2.pkl --lora checkpoints/needle_lora.pkl --out my_needle.cact

Errores comunes

Error: tratar Needle como un chatbot pequeño. No tiene fallback a texto libre por diseño; cualquier caso de uso conversacional fuera del tool calling o la extracción no encaja. Solución: deriva la conversación abierta a un modelo de propósito general y mantén Needle limitado a acciones estructuradas.

Error: declarar un catálogo grande de herramientas sin tener en cuenta el retrieval. Más allá de cinco herramientas, solo las cinco candidatas recuperadas con mejor puntuación son accesibles por turno. Solución: escribe descripciones de herramientas claras y distintas para que la cabeza de retrieval realmente pueda diferenciarlas.

Error: ignorar el campo de confianza. Aceptar cualquier llamada que vuelva sin comprobar la confianza desperdicia la propia señal del modelo sobre cuán seguro está. Solución: establece un umbral real por acción y construye una ruta de escalado para cualquier cosa que quede por debajo.

Error: poner instrucciones de comportamiento en el campo de hechos del sistema. El modelo está entrenado para tratar ese campo como datos, no como comandos, por lo que las instrucciones colocadas ahí no lo dirigirán. Solución: pon la guía de comportamiento en las descripciones y esquemas de herramientas, donde el modelo realmente la lee como directiva.

Error: saltarse el fine-tuning para una ontología de herramientas muy específica. El modelo base es de propósito general dentro del tool calling; un catálogo estrecho o inusual puede no ser su mejor encaje tal como viene. Solución: el fine-tuning con LoRA sobre tus propios esquemas es lo bastante barato como para que merezca la pena hacerlo antes de asumir que la precisión ya ha tocado techo.

Buenas prácticas para producción

• Lleva las restricciones al esquema, no a la validación posterior. Los rangos, patrones y enums declarados desde el principio se hacen cumplir durante la generación, no se detectan después.
• Construye una ruta de escalado real en torno a la puntuación de confianza. Decide por acción qué debe ocurrir “por debajo del umbral”: reintentar, hacer una pregunta aclaratoria o derivar a un modelo más grande.
• Mantén las descripciones de herramientas distintas y específicas, especialmente una vez que dependas de la cabeza de retrieval para un catálogo más grande.
• Trata el campo de hechos del sistema solo como datos. No confíes en él para dirigir el comportamiento: no es para eso para lo que está entrenado.
• Haz fine-tuning pronto si tu catálogo de herramientas es inusual. Un paso barato de LoRA sobre tus propios esquemas es un coste pequeño frente al riesgo de lanzar con una precisión del modelo base que no esté ajustada a tu dominio.

Cierre

La historia real aquí no es “un modelo de 26M puede hacer function calling”; ese enfoque en realidad se queda corto frente a lo que ya se ha lanzado, ya que Needle 2 ha ido más allá con una arquitectura diseñada específicamente para ello, salida estructurada garantizada por gramática y un contrato de confianza pensado para el escalado en producción. La idea subyacente es la que merece la pena conservar: no toda tarea de IA necesita un modelo de mil millones de parámetros, y una vez sabes con precisión qué necesita hacer un modelo, gastar todo su presupuesto de parámetros en hacer bien esa única cosa supera a gastar la mayor parte en capacidad general que nunca usarás.

¿Estás viendo a más equipos recurrir a modelos diminutos especializados como este para las partes estrechas y estructuradas de su stack de agentes, o la atracción hacia un único gran modelo de propósito general sigue imponiéndose en la práctica?