9 min di lettura 7 giugno 2026

Configurare Odysseus AI con Ollama: collegare un modello locale

Guida mirata alla configurazione di Odysseus AI con Ollama in Docker e in modalità nativa, con endpoint, controlli dei modelli e troubleshooting.

Odysseus AI Wiki
Odysseus AI Wiki
Note editoriali non ufficiali basate sulla documentazione pubblica di Odysseus AI e su modelli di self-hosting locale.
Diagramma della configurazione Odysseus AI con Ollama e endpoint di modelli locali

Risposta rapida: Per Odysseus AI in Docker e Ollama sull’host, prova prima http://host.docker.internal:11434/v1. Se entrambi i servizi sono nativi sulla stessa macchina, inizia da http://127.0.0.1:11434/v1. Controlla poi che Ollama sia attivo e che esista un modello prima di modificare il provider.

In questa guida

Configurare Odysseus AI con Ollama richiede due controlli separati: il server Ollama deve rispondere e Odysseus AI deve raggiungerlo dalla rete del runtime corretto. Questa guida copre Docker verso l’host, i setup nativi Windows/Linux/macOS, gli esempi di modelli locali e il caso in cui il provider si colleghi ma non mostri modelli.

Scegli l’endpoint Ollama in base al runtime

L’errore più comune nella configurazione Odysseus AI con Ollama è copiare un URL localhost nativo dentro un container Docker. L’endpoint deve essere raggiungibile dal processo Odysseus, non solo dal computer su cui Ollama è installato.

Usa host.docker.internal:11434/v1 quando Odysseus AI gira in Docker e Ollama sull’host. Usa 127.0.0.1:11434/v1 quando entrambi sono nativi. Verifica Ollama e un modello prima di analizzare prompt o agenti.

Endpoint Ollama dall’host al container Docker
http://host.docker.internal:11434/v1

Configurare Docker verso Ollama sull’host

Una configurazione Odysseus AI con Ollama in Docker attraversa un confine di rete. localhost nel container indica il container stesso; l’endpoint dell’host deve quindi essere esplicito e Ollama deve ascoltare su un indirizzo raggiungibile.

Mantieni il primo test locale: dimostra una sola rotta tra container e Ollama prima di esporre porte o cambiare i tag dei modelli.

1. Avvia Ollama affinché ascolti oltre il proprio loopback quando necessario

Se Docker non raggiunge Ollama, avvialo con un host binding esplicito. Limitalo all’uso locale fidato se non conosci l’esposizione di rete.

OLLAMA_HOST=0.0.0.0:11434 ollama serve

2. Verifica che Ollama abbia almeno un modello

Odysseus AI può raggiungere l’endpoint ma non mostrare modelli utili se Ollama non ne ha ancora scaricati. Per testare solo la connessione, scarica prima un modello piccolo.

ollama list
ollama pull llama3.2:3b

3. Inserisci l’endpoint Docker nelle impostazioni di Odysseus AI

Usa la base URL compatibile OpenAI nelle impostazioni del modello o del servizio. Non usare localhost in questo percorso Docker-host salvo diversa configurazione Docker.

http://host.docker.internal:11434/v1

4. Controllare la salute del container prima di analizzare i prompt

Se il servizio Odysseus è degradato, correggilo prima. Un endpoint modello non ripara un avvio container rotto, un file ambiente mancante o una dipendenza non sana.

docker compose ps
docker compose logs --tail=120 odysseus

Configurazione nativa di Ollama su Windows, Linux e macOS

Quando Odysseus AI e Ollama girano nativamente nella stessa sessione, localhost indica di solito la macchina prevista. La porta dell’interfaccia può cambiare, ma Ollama usa spesso 11434 se OLLAMA_HOST non è stato modificato.

Per la scelta su Mac continua con la guida macOS; per Windows e hardware usa le pagine esistenti di setup e requisiti senza allargare l’intento di questa guida.

Configurazione Endpoint da provare per primo Cosa controllare
Odysseus nativo su Windows + Ollama su Windows http://127.0.0.1:11434/v1 Usa localhost quando entrambi i servizi girano nativamente sulla stessa macchina Windows.
Odysseus nativo su Linux + Ollama http://127.0.0.1:11434/v1 Controlla i permessi del servizio se uno dei processi gira come servizio in background.
Percorso nativo macOS o Apple Silicon http://127.0.0.1:11434/v1 La porta dell’interfaccia Odysseus può variare, ma Ollama resta di solito sulla 11434.
Odysseus in Docker + Ollama sull’host http://host.docker.internal:11434/v1 Usa il nome host Docker perché il localhost del container non è la macchina host.

Risolvere gli errori di provider ed endpoint Odysseus AI Ollama

Leggi gli errori per livelli: processo Ollama, endpoint raggiungibile, modello elencato, configurazione provider e infine prompt. Così un problema di rete non sembra un problema del modello.

Sintomo Causa probabile Soluzione
Connessione rifiutata Ollama non è in esecuzione o ascolta solo dove Odysseus non può raggiungerlo. Avvia Ollama, conferma la porta 11434 e usa un binding OLLAMA_HOST esplicito per il test Docker-host.
Il browser dell’host funziona ma Docker fallisce L’endpoint usa localhost dentro il container. Passa l’endpoint a http://host.docker.internal:11434/v1.
Nessun modello visualizzato Non è stato scaricato alcun modello oppure il tag è errato. Esegui ollama list, scarica un modello piccolo e seleziona il tag esatto.
Prima risposta lenta Il modello si sta caricando o è troppo grande per la macchina. Prova un modello più piccolo prima di agenti, strumenti o documenti.
Esposizione LAN imprevista Un servizio è stato associato a tutte le interfacce senza un confine di fiducia. Torna al binding solo localhost, salvo che firewall, VPN e autenticazione siano configurati intenzionalmente.

Checklist finale prima di fidarti del setup

Una configurazione funzionante deve superare questi controlli in ordine. Fermati al primo errore e correggi quel livello prima di proseguire.

  1. Ollama risponde sull’host e ollama list mostra un modello.
  2. Il servizio Odysseus è sano nei log Docker o nativi.
  3. L’endpoint corrisponde alla struttura del runtime.
  4. Un prompt piccolo funziona prima di agenti o workflow documentali più grandi.
  5. Ogni esposizione alla LAN è autenticata e intenzionale.
Mantieni locale il primo setup

Collegare Odysseus AI a Ollama non richiede di pubblicare i servizi su Internet. Mantienili locali finché autenticazione, firewall e reverse proxy non sono stati definiti intenzionalmente.

Note di verifica 2026 per configurare Odysseus AI con Ollama

Prima di cambiare il nome del modello verifica il confine del runtime e la base URL. Lo stesso server Ollama può usare localhost in nativo e host.docker.internal dal container.

Un esempio sicuro: elenca un modello, prova l’endpoint dallo stesso livello di esecuzione di Odysseus AI e poi salva il provider. Se la prima richiesta fallisce, non cambiare ancora il tag del modello.

Verifica Risultato corretto Se fallisce
API Ollama dell’host L’host raggiunge http://127.0.0.1:11434 prima che intervenga Odysseus. Avvia Ollama, scarica un modello piccolo e prova prima l’API.
Percorso Docker verso l’host Odysseus nel container usa host.docker.internal:11434/v1. Non usare localhost nel container, salvo che Ollama sia nella stessa rete.
Percorso nativo Odysseus nativo usa 127.0.0.1:11434/v1 quando Ollama è sulla stessa macchina. Rimuovi i nomi host specifici di Docker e prova con un prompt piccolo.
  1. La nuova sezione separa Docker, esecuzione nativa ed endpoint Ollama prima di modificare le impostazioni.
  2. Aggiornata con note 2026 su fonti ufficiali, esecuzione locale, Ollama e guide correlate.
  3. Mantieni distinto l’intento di questa pagina dalle guide di configurazione correlate.

FAQ: configurare Odysseus AI con Ollama

Inizia con http://host.docker.internal:11434/v1 quando Odysseus AI è in Docker e Ollama sull’host. Se non funziona, controlla binding e rete Docker prima di cambiare modello.

Usa la base compatibile OpenAI con /v1 quando il campo provider richiede questo formato. Segui la documentazione e prova l’URL esatto.

No. In questa configurazione Ollama è un server di modelli separato. Odysseus AI si collega, ma non avvia Ollama nel container.

Se Odysseus AI e Ollama girano nativamente su Windows, prova prima http://127.0.0.1:11434/v1. Usa host.docker.internal solo quando Odysseus è in Docker e Ollama sull’host.

Il server può rispondere senza un modello scaricato o con un tag diverso. Esegui ollama list, conferma il tag e poi controlla il campo modello in Odysseus AI.

Di solito sì. Ollama è il server dei modelli e Odysseus AI è il workspace che si collega. Avvia i due livelli separatamente e verifica il collegamento.

Fonti e riferimenti ufficiali

  1. Repository GitHub ufficiale di Odysseus AI - Indicazioni su Docker, Windows, Apple Silicon ed endpoint Ollama.
  2. Documentazione dell’API Ollama - Comportamento dell’API del server di modelli locale.
  3. Documentazione di rete di Docker Desktop - Comportamento della rete host con host.docker.internal.

Guide di configurazione Odysseus AI correlate

Ultimo aggiornamento: 13 agosto 2026

Torna alla Wiki di Odysseus AI