Clasificador Automático de Frutas con IA

Sistema de clasificación física en tiempo real que combina Visión Artificial local con Arduino

Descripción del Proyecto

Este proyecto es un sistema de clasificación de frutas completamente automatizado que utiliza Inteligencia Artificial local y hardware de código abierto para identificar y separar físicamente manzanas y naranjas.

El sistema funciona de la siguiente manera: una fruta se coloca en una rampa; un sensor ultrasónico detecta su presencia, una webcam captura la imagen y un modelo de visión artificial (Qwen3-VL ejecutado localmente en LMStudio) identifica de qué fruta se trata. Finalmente, servomotores controlados por Arduino desvían la fruta hacia el contenedor correcto.

Todo el proceso es orquestado por un servidor MCP (Model Context Protocol) escrito en Python con FastMCP. El usuario interactúa con el sistema a través del chat de LMStudio: simplemente escribe "Iniciar" y el modelo Qwen3-VL llama automáticamente las herramientas MCP para operar todo el pipeline.

Características Principales

• Completamente Automático — Operación continua en bucle infinito sin intervención manual una vez iniciado.
• Inferencia 100% Local — Sin dependencias de la nube. El modelo de IA corre localmente con LMStudio.
• Hardware Accesible — Componentes económicos y fáciles de conseguir.
• Protocolo MCP — Controlable mediante lenguaje natural desde el chat de LMStudio a través de FastMCP.
• Validación Multi-foto — Sistema de votación con múltiples capturas para reducir errores de clasificación.

Hardware

Componentes utilizados

Diagrama del Circuito

Conexiones de pines

Maqueta Física

Arquitectura del Sistema

LMStudio cumple un doble rol en este sistema: es la interfaz donde el usuario interactúa con el modelo (chat + MCP tools) y también sirve como servidor de visión artificial (API en puerto 1235) para clasificar las imágenes.

graph LR
    A["LMStudio<br/>Chat + MCP Client<br/>(Qwen3-VL 4B)"]
    B["server.py<br/>FastMCP Server"]
    C["LMStudio<br/>Vision API<br/>(localhost:1235)"]
    D["Arduino UNO R3<br/>Sensor + Servos"]

    A <-->|"lenguaje natural · streamable-http"| B
    B -->|"HTTP API · /v1/chat/completions"| C
    B -->|"Serial · 115200 baud"| D

Flujo de un ciclo completo

flowchart TD
    A["Inicio del ciclo"] --> B["Enviar WAIT_FRUIT"]
    B --> C{"¿Detectada?"}
    C -- "TIMEOUT" --> B
    C -- "DETECTED" --> D["Esperar estabilización"]
    D --> E["Capturar foto"]
    E --> F["Clasificar con Qwen3-VL"]
    F --> G{"¿Confirmada?"}
    G -- "unknown" --> H["Descartar y reiniciar"]
    H --> B
    G -- "apple/orange" --> I["Enviar comando"]
    I --> J["Accionar servo"]
    J --> K["Ciclo completado"]
    K --> B

Comunicación entre componentes

1. server.py ↔ Arduino (Serial, 115200 baud)

El servidor Python envía comandos de texto por el puerto serial y espera una respuesta:

2. server.py ↔ LMStudio (HTTP API, localhost:1235)

El servidor captura un frame de la webcam con OpenCV, lo codifica a JPEG en base64 y lo envía como imagen al endpoint /v1/chat/completions de LMStudio. El modelo Qwen3-VL analiza la imagen y devuelve la clasificación.

Software — Partes Esenciales del Código

Prompt de Clasificación de la IA

Este es el prompt exacto que se envía al modelo de visión para clasificar cada fruta. Está diseñado para ser extremadamente restrictivo: el modelo solo puede responder con una de tres palabras, evitando respuestas ambiguas o fuera de rango:

"You are a fruit classification system for a sorting machine. "
"Look at this image carefully and identify the fruit.\n\n"
"Rules:\n"
"- If you see an apple (any color: red, green, yellow), respond: apple\n"
"- If you see an orange (round citrus fruit), respond: orange\n"
"- If you see no fruit, or the image is unclear, respond: unknown\n\n"
"Reply with ONLY one word: apple, orange, or unknown.\n"
"No punctuation, no explanation, no extra text."

¿Por qué funciona?

• temperature: 0 — Elimina la aleatoriedad. El modelo siempre da la respuesta más probable.
• max_tokens: 10 — Limita la respuesta a pocas palabras, evitando que el modelo "hable de más".
• Parseo con fallback — Aunque el modelo agregue texto extra, el código extrae la keyword (apple, orange) si aparece en la respuesta.

Tools MCP (Herramientas del servidor)

El servidor expone 7 herramientas via MCP que el modelo en LMStudio puede invocar:

Cómo se comunican las Tools entre sí

El sistema tiene dos modos de operación:

Modo Manual — El modelo invoca las tools una por una:

flowchart LR
    A[wait_for_fruit] --> B[classify_fruit] --> C["sort_fruit('apple')"]

Modo Automático — El flujo completo corre en un thread en segundo plano:

sequenceDiagram
    participant M as Modelo (LMStudio)
    participant T as Thread en segundo plano

    M->>T: start_sorting_loop()
    loop cada ciclo
        T->>T: wait_for_fruit
        T->>T: classify_with_retries
        T->>T: sort_fruit
    end
    loop cada ~5 segundos
        M->>T: get_loop_status()
        T-->>M: eventos nuevos
        note over M: Narra los eventos<br/>al usuario en español
    end
    M->>T: stop_sorting_loop()

El campo instructions del servidor MCP instruye al modelo Qwen3-VL (en LMStudio) a:

1. Llamar start_sorting_loop() cuando el usuario diga "iniciar"
2. Llamar get_loop_status() automáticamente cada 3-5 segundos
3. Traducir los eventos a lenguaje natural en español
4. Nunca preguntar si desea continuar

Protocolo Serial del Arduino

El Arduino implementa un protocolo serial simple basado en texto. Cada comando termina en \n y cada respuesta termina en \n:

sequenceDiagram
    participant S as server.py
    participant A as Arduino

    S->>A: WAIT_FRUIT
    A-->>S: DETECTED (sensor < 15 cm)

    S->>A: APPLE
    note over A: Servo manzana → 135°<br/>Servo naranja empuja (105°)<br/>Ambos vuelven a 90°
    A-->>S: OK

El mecanismo de empuje es clave: cuando se clasifica una manzana, el servo de la manzana abre la compuerta (135°) y el servo de la naranja hace un pequeño empuje (de 90° a 105°) para ayudar a la fruta a rodar hacia el contenedor. Lo mismo ocurre a la inversa.

Demo

Configuración Rápida

1. LMStudio

• Descarga e instala LMStudio.
• Carga el modelo qwen/qwen3-vl-4b (o cualquier modelo de visión compatible con herramientas).
• Inicia el servidor de visión en el puerto 1235:

  lms server start --port 1235
  

2. Arduino

• Abre fruit_sorter.ino en el IDE de Arduino.
• Conecta los componentes según el diagrama del circuito.
• Carga el sketch en tu Arduino UNO.

3. Python

# Instalar dependencias
pip install fastmcp opencv-python pyserial requests

# Configurar el puerto serial en server.py (ej. COM5 en Windows, /dev/ttyACM0 en Linux)
# Ejecutar el servidor MCP
fastmcp run server.py:app --transport=http

4. Usar el sistema

• En LMStudio, abre un chat con el modelo qwen3-vl-4b.
• Las herramientas MCP del servidor aparecerán automáticamente.
• Escribe "Iniciar" en el chat y el modelo activará el sistema automático de clasificación.

Estructura del Repositorio

fruit_sorter/
├── server.py              # Servidor FastMCP — orquesta IA, cámara y Arduino
├── fruit_sorter.ino       # Sketch de Arduino — control de servos y sensor
├── assets/
│   ├── circuit_diagram.png   # Diagrama del circuito (Tinkercad)
│   ├── demo.gif              # GIF con demostración del funcionamiento
│   └── maqueta.jpeg          # Fotografía de la maqueta física
└── README.md              # Este archivo

Desarrolladores

Jesús Andrés Mondragón Tenorio

Cristofer Piña Rodriguez

Mauricio Sanchez Garcia