Primo test con un modello LLM

Questa pagina è un punto di partenza facoltativo. Non è un prerequisito per usare gli agenti di ALIDA: serve a prendere confidenza con i modelli LLM della piattaforma e a verificare, con due comandi curl, che l'accesso funzioni.

Modello e agente non sono la stessa cosa

Qui si dialoga direttamente con un modello, non con un agente. La distinzione è la cosa più importante da chiarire prima di proseguire.

Un modello LLM è servito da Ollama ed è raggiungibile come un normale endpoint HTTP. Riceve un testo, restituisce un testo e termina lì: non ha memoria della conversazione precedente, non ha strumenti, non conosce il contesto ALIDA in cui si sta lavorando. È esattamente ciò che si prova in questa pagina.

Un agente è invece un Service ALIDA che usa un modello: mantiene la sessione, può usare strumenti e server MCP, lavora su repository e dataset, e viene collegato alla chat della piattaforma. Un agente è un componente long-running, con le sue porte esposte, e non un endpoint di modello.

Gli agenti vanno deployati in un workflow

Gli agenti distribuiti con ALIDA sono due: l'agente OpenCode e l'agente ADK. Non esiste un elenco di agenti «già serviti» dalla piattaforma a cui collegarsi: ciascuno dei due va inserito in un workflow, configurato con le sue porte e avviato. Solo mentre quel workflow è in esecuzione l'agente espone gli endpoint che la chat richiama, come descritto in Configurare e usare la chat.

I modelli sono serviti da Ollama

ALIDA usa Ollama e offre sia le API native sia endpoint compatibili con OpenAI. Le sezioni seguenti mostrano come raggiungerlo, elencare i modelli disponibili e ottenere una prima risposta.

Due modi per raggiungere i modelli

Gli stessi modelli sono raggiungibili in due modi, che differiscono per chi media la chiamata e per come la chiamata viene autenticata.

	Gateway ALIDA	Accesso diretto a Ollama
URL di base	https://<url-istanza-alida>/events/ollama/ollama-user	https://ollama.develop.alidalab.it
Chi risponde	ALIDA, che autentica il chiamante e inoltra la richiesta a Ollama	Il server Ollama, contattato direttamente
Autenticazione	Authorization: Apikey <api-key>, con un'API key creata nell'interfaccia ALIDA	Authorization: Basic <credenziali-base64>, con credenziali rilasciate da un amministratore
Quando usarlo	Tutto ciò che opera in ALIDA: agenti, servizi, notebook e i propri test	Solo se si dispone di credenziali autorizzate per l'istanza di develop e serve escludere la piattaforma

Il gateway ALIDA è la scelta consigliata: la chiamata viaggia con la propria identità ALIDA, quindi l'accesso segue i ruoli e i permessi già definiti nella piattaforma, e l'URL resta valido per l'istanza su cui si lavora. Ad esempio, il gateway dell'istanza devng è https://alida.devng.alidalab.it/events/ollama/ollama-user.

L'accesso diretto a https://ollama.develop.alidalab.it dialoga con il server Ollama senza passare da ALIDA. È utile per il debug, ma richiede credenziali separate e non offre alcun controllo lato ALIDA sulla chiamata.

Entrambi espongono le stesse due famiglie di API:

• API Ollama native, sotto /api, ad esempio /api/tags e /api/generate.
• API compatibili con OpenAI, sotto /v1, ad esempio /v1/models e /v1/chat/completions.

Le chiamate ai modelli sono normali endpoint HTTP, quindi l'URL di base scelto qui è lo stesso valore da indicare a qualsiasi componente debba dialogare con il modello: la configurazione del modello di un agente ADK, un client compatibile con OpenAI come Open WebUI o LangChain, oppure un semplice curl come quelli seguenti. I client che si aspettano un endpoint OpenAI richiedono la forma dell'URL con /v1 e accettano l'API key ALIDA come propria API key.

Gateway ALIDA

WARNING

Per creare un'API key da usare con gli agenti, è necessario avere il ruolo ollama-user in ALIDA. Contattare un amministratore per richiederne l'abilitazione.

Preparare le variabili

export ALIDA_URL='https://<url-istanza-alida>'
export ALIDA_API_KEY='<api-key-generata-dall-ui-alida>'

La procedura per creare la chiave è descritta nella guida alle API key.

Elencare i modelli

Prima di inviare una richiesta, recuperare il catalogo e scegliere un valore da usare al posto di <modello>.

API Ollama native

curl -sS \
  "${ALIDA_URL}/events/ollama/ollama-user/api/tags" \
  -H "Authorization: Apikey ${ALIDA_API_KEY}"

API compatibili con OpenAI

curl -sS \
  "${ALIDA_URL}/events/ollama/ollama-user/v1/models" \
  -H "Authorization: Apikey ${ALIDA_API_KEY}"

Generare una prima risposta

Il parametro "stream": false restituisce una sola risposta JSON, utile per un primo test.

API Ollama native

curl -sS \
  "${ALIDA_URL}/events/ollama/ollama-user/api/generate" \
  -H "Authorization: Apikey ${ALIDA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<modello>",
    "prompt": "Hello world",
    "stream": false
  }'

API compatibili con OpenAI

curl -sS \
  "${ALIDA_URL}/events/ollama/ollama-user/v1/chat/completions" \
  -H "Authorization: Apikey ${ALIDA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<modello>",
    "messages": [
      {"role": "user", "content": "Hello world"}
    ],
    "stream": false
  }'

Accesso diretto a Ollama

Usare questa modalità solo se si dispone delle credenziali autorizzate per l'accesso diretto all'istanza di develop.

WARNING

L'API key per l'istanza di develop non può essere generata automaticamente: sarà necessario contattare un amministratore per richiederla.

Preparare le variabili

export OLLAMA_DEVELOP_URL='https://ollama.develop.alidalab.it'
export OLLAMA_DEVELOP_BASIC_AUTH='<credenziali-basic-codificate-in-base64>'

Elencare i modelli

Prima di inviare una richiesta, recuperare il catalogo e scegliere un valore da usare al posto di <modello>.

API Ollama native

curl -sS "${OLLAMA_DEVELOP_URL}/api/tags" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}"

API compatibili con OpenAI

curl -sS "${OLLAMA_DEVELOP_URL}/v1/models" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}"

Generare una prima risposta

API Ollama native

curl -sS "${OLLAMA_DEVELOP_URL}/api/generate" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<modello>",
    "prompt": "Hello world",
    "stream": false
  }'

API compatibili con OpenAI

curl -sS "${OLLAMA_DEVELOP_URL}/v1/chat/completions" \
  -H "Authorization: Basic ${OLLAMA_DEVELOP_BASIC_AUTH}" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<modello>",
    "messages": [
      {"role": "user", "content": "Hello world"}
    ],
    "stream": false
  }'

Dopo aver verificato il modello, scegliere e preparare un agente OpenCode o un agente ADK. Configurare la chat solo dopo che l'agente è stato deployato e avviato.