Guida di Configurazione: Local Sovereign AI (Livello 1) #

Questa guida documenta la configurazione dell’ambiente offline per la Refertazione Ambientale Vocale di Livello 1 dell’Agenda Aura, spiegando i requisiti hardware, l’architettura tecnica del localhost bridge e le istruzioni operative sia per l’attivazione automatica 1-click sia per la configurazione manuale sviluppatori.

1. Architettura del Sistema (Local Whisper + Ollama) #

Il Livello 1 è progettato per garantire il 100% della privacy del dato biologico (nessun dato sensibile lascia il computer dello specialista) sfruttando l’hardware locale per trascrivere e strutturare le note cliniche. Utilizziamo Whisper locale integrato (tramite Aura Desktop o model WASM locale in fallback, ~64MB, Web Workers, WebGPU) che garantisce accuratezza superiore al riconoscimento vocale nativo del browser, specialmente in italiano e terminologia clinica.

[Clinico parla in studio] ──(Registrazione Audio PCM)──> [Agenda Aura (Interfaccia Clinica)]
                                                             │
  ┌──────────────────────────────────────────────────────────┘
  ▼
[browser-whisper (tiny, Web Worker)] ──> [Trascrizione Testuale Accurate]
                                                             │
  ┌──────────────────────────────────────────────────────────┘
  ▼
[Testo Accumulato] ──(POST /api/chat - qwen2.5:1.5b)──> [Ollama Locale (127.0.0.1:11435)]
                                                             │
  ┌──────────────────────────────────────────────────────────┘
  ▼
[JSON Strutturato SOAP] ──(Popolamento Campi)──> [Diario Clinico (Scheda Clinica)]

Three-tier ASR Fallback (dal più accurato al più compatibile):

1. Tauri Desktop + sherpa-onnx: Se l’utente ha installato Aura Desktop, il sidecar sherpa-onnx-vad-with-offline-asr (26MB) gestisce l’ASR via Rust invoke.
2. browser-whisper (tiny): Modello ~64MB caricato via Web Worker. Download automatico al primo click con progress UI. Zero dipendenze server.
3. Web Speech API (fallback nativo): Se nessuna delle precedenti è disponibile, usa il riconoscimento vocale del browser (accuratezza ridotta ma zero setup).

Endpoint di Connessione Standard:

• Whisper ASR: Elaborato interamente nel browser (Web Worker + WebGPU) — nessun server aggiuntivo richiesto
• Ollama API (Zero-Drafting SOAP): http://127.0.0.1:11435/api/chat (Modello: qwen2.5:1.5b — ~986 MB download, ~1.8 GB su disco, strutturazione SOAP dei campi clinici)

2. Specifiche Hardware e Requisiti di Sistema #

3. Attivazione Automatica — Aura Desktop Installer (Per il Professionista) #

Per evitare la frizione d’uso, Dottori-Online ha sviluppato Aura Desktop, un’applicazione Tauri che automatizza completamente l’infrastruttura AI locale:

1. Scarica l’Installer: Clicca sul pulsante “Scarica Aura Desktop” su dottori-online.com/agenda-clinica o dalle impostazioni dell’Agenda.
2. Installa: Esegui il file .dmg (macOS) o .exe/.msi (Windows). L’app viene installata in /Applications/Aura.app. Versione minima consigliata: v1.0.8+ (include la richiesta permessi microfono per macOS).
3. Nessuna configurazione: L’installer attiva automaticamente un LaunchAgent che avvia Ollama bundle (porta 11435) e il sidecar sherpa-onnx all’avvio del computer. Nessun terminale, nessun comando.
4. Inizia a Dettare: Apri l’Agenda nel browser. L’AI locale è già attiva su localhost:11435. Se hai già Ollama installato, non c’è conflitto — Aura usa la porta 11435, la tua installazione esistente resta su 11434.

Cosa include Aura Desktop:

• Ollama bundle (~64MB) con qwen2.5:1.5b pre-configurato su porta 11435
• Sherpa-onnx sidecar (~26MB) per ASR offline via Rust invoke
• Modelli ONNX sherpa-onnx (~106MB) per trascrizione vocale offline
• LaunchAgent auto-avviante con OLLAMA_ORIGINS=* e OLLAMA_HOST=127.0.0.1:11435
• App gestionale per monitorare stato Ollama, modelli e microfono
• Richiesta permesso microfono (NSMicrophoneUsageDescription) integrata in Info.plist da v1.0.8

4. Configurazione Manuale per Sviluppatori #

Se desideri configurare manualmente l’ambiente o effettuare dei test personalizzati, apri il Terminale del tuo computer ed esegui le seguenti istruzioni:

Step 1: Setup di Ollama e Gemma-4

1. Scarica e installa Ollama da Ollama.com.
2. Scarica il modello linguistico raccomandato per lo Zero-Drafting digitando nel terminale:

   # Modello consigliato (massima precisione e contesto):
   ollama pull gemma4:e4b
   
   # In alternativa (Consigliato per connessioni lente o PC 8GB RAM):
   ollama pull qwen2.5:1.5b

3. Verifica che Ollama sia in esecuzione:

   curl http://127.0.0.1:11435/api/tags

Step 2: Browser SpeechRecognition (Nativo — nessuna installazione)

La trascrizione vocale utilizza il riconoscimento vocale nativo del browser. Non è richiesta alcuna installazione. Assicurati solo di:

• Usare Google Chrome o Microsoft Edge (Safari ha supporto parziale, Firefox non è supportato).
• Concedere il permesso Microfono al sito (sia a livello browser che nelle Impostazioni di Sistema di macOS → Privacy → Microfono).

Step 3: Mock Mode (Test UI senza CPU)

Se non hai Ollama installato o vuoi testare l’interfaccia senza caricare la CPU:

1. Apri il Setup Panel nell’Editor Note Cliniche (icona ingranaggio).
2. Attiva il toggle Mock Mode (Simula AI).
3. La refertazione ambientale ora userà dati simulati istantanei — nessuna chiamata a Ollama.

Lo stato persiste tra le sessioni (salvato automaticamente). Disattivalo quando Ollama è pronto per tornare alla modalità AI reale.

Una volta che Ollama è in esecuzione, l’interfaccia dell’Agenda lo rileverà all’avvio abilitando il servizio di Refertazione Ambientale vocale offline.

5. Risoluzione Errore “no-speech” del Browser #

L’errore no-speech fornito dal browser è una diagnosi cruciale durante la refertazione vocale. Significa che:

• Il browser ha inizializzato correttamente il motore SpeechRecognition.
• La pagina web ha i permessi per usare il microfono (altrimenti vedresti l’errore not-allowed).
• Il motore vocale del browser riceve silenzio assoluto dal sistema operativo, andando in timeout.

Su macOS questo comportamento è molto comune ed è legato ai permessi a livello di Sistema Operativo o alla selezione del dispositivo di input. Segui questa checklist:

Passo 1: Permessi Microfono di macOS

Su Mac, anche se dai il permesso al sito all’interno del browser, macOS potrebbe bloccare l’accesso al microfono per l’intera applicazione:

1. Apri le Impostazioni di Sistema di macOS.
2. Vai su Privacy e Sicurezza → Microfono.
3. Assicurati che l’interruttore accanto a Google Chrome (o al browser in uso) sia abilitato (colore blu/verde). Se è disattivato, Chrome riceverà solo silenzio.
4. Ricarica la pagina dopo aver attivato il permesso.

Passo 2: Dispositivo di Input predefinito

Se hai più microfoni collegati (es. monitor esterni, cuffie, microfoni virtuali come Camo/EpocCam/BlackHole):

1. In Chrome, vai su chrome://settings/content/microphone (copia e incolla nella barra degli indirizzi).
2. Controlla quale dispositivo è selezionato nel menu a tendina in alto.
3. Assicurati che sia selezionato il microfono integrato del Mac (es. “Microfono integrato”) o le tue cuffie attive, e non un ingresso audio virtuale silente.

Passo 3: Volume del Microfono di macOS

1. Vai in Impostazioni di Sistema → Suono → scheda Ingresso.
2. Parla e verifica se la barra del volume di ingresso si muove.
3. Se è a zero o molto bassa, il browser non rileverà la voce e andrà in no-speech.

6. Raccomandazioni Modelli e Note Tecniche #

Modelli Ollama Raccomandati (in ordine di priorità):

Comandi rapidi per scaricare i modelli:

# Modello consigliato (Alta precisione e contesto 128K)
ollama pull gemma4:e4b

# Alternativa ultra-leggera (Consigliata per connessioni lente)
ollama pull qwen2.5:1.5b

# Altre alternative:
ollama pull gemma4:e2b
ollama pull llama3.2

# DA EVITARE su Mac con ≤16 GB RAM:
# ollama pull llama3       # 8B - causa freeze e swap intensivo

Variabili d’ambiente consigliate per Ollama:

# Limita l'utilizzo delle risorse (fondamentale su Mac 16 GB)
export OLLAMA_NUM_PARALLEL=1
export OLLAMA_MAX_LOADED_MODELS=1
export OLLAMA_KEEP_ALIVE=5m
export OLLAMA_NUM_THREAD=4

Nota su Whisper in-browser (browser-whisper):

L’architettura utilizza browser-whisper (modello tiny, 64MB) in esecuzione su Web Worker, che risolve i problemi della Web Speech API nativa (bassa accuratezza italiano, terminologia clinica non riconosciuta). Vantaggi rispetto a whisper.cpp nativo:

• Zero installazione: Il modello tiny (~64MB) viene scaricato automaticamente al primo click con progress UI.
• Web Worker: Esecuzione in thread separato, non blocca la UI né compete con Ollama.
• WebGPU opzionale: Se disponibile, accelera l’inferenza senza consumare CPU.
• Tre path ASR: Tauri (sherpa-onnx sidecar) → browser-whisper → Web Speech API (fallback).

Raccomandazione finale: Usare Aura Desktop (Ollama bundle su :11435 + sherpa-onnx) per la massima accuratezza. In assenza di Aura Desktop, il browser carica automaticamente whisper tiny. Mock Mode disponibile per test UI senza CPU.