Usare l'IA negli script
Chiedere testo, JSON con una forma precisa ed embeddings ai modelli di IA dell'app, inviare file, gestire gli errori e sapere cosa fa ogni fornitore.
Gli script dell'app chiamano l'IA con il modulo ai dell'SDK. Lo script
sceglie il modello con il nome dell'alias, e la richiesta parte dal server della
piattaforma con le credenziali del fornitore. Lo script non vede mai le chiavi.
from api_manager import ai
def main(input):
r = ai.chat("Resume em três frases: " + input["args"]["texto"])
return {"resumo": r["text"]}
Prima di cominciare
- Il tenant deve avere un fornitore di IA attivo, con modelli autorizzati. Vedi Fornitori di IA.
- L'app deve avere un alias per ogni uso che lo script chiede. Senza
model=, lo script usa l'alias predefinito di quell'uso. Vedi Modelli di IA dell'app.
Cosa fa ogni fornitore
| Fornitore | Testo, JSON e strumenti | Embedding | Immagini | Trascrizione | Voce | Lotti |
|---|---|---|---|---|---|---|
| OpenAI | Sì | Sì | Sì | Sì | Sì | Sì |
| Anthropic | Sì | No | No | No | No | Sì |
| Microsoft Foundry | Sì | Sì | Sì | Sì | Sì | No |
| Amazon Bedrock | Sì | Titan e Cohere | Nova Canvas, Titan e Stability | No | No | No |
| Google Cloud | Sì | Sì | Sì | Sì | Sì | Solo tramite la Gemini API |
| OpenRouter | Sì | Sì | Sì | No | No | No |
| Compatibile con OpenAI | Sì | Dipende dal server | Dipende dal server | Dipende dal server | Dipende dal server | No |
Con un fornitore che non fa un'operazione, la chiamata dà l'errore
not_supported. Con qualsiasi fornitore, l'operazione funziona solo con un
modello che la fa: un modello di testo non genera immagini.
Gli strumenti e i lotti sono in Strumenti e lotti, e le immagini, la trascrizione e la voce in Immagini e audio.
Chiedere testo
ai.chat invia una richiesta e restituisce la risposta del modello:
from api_manager import ai, log
def main(input):
r = ai.chat(
"Classifica este pedido de suporte: " + input["args"]["pedido"],
system="És um assistente de apoio ao cliente. Respondes numa palavra: urgente, normal ou baixo.",
model="texto",
max_tokens=10,
temperature=0,
)
log("classificação:", r["text"], r["usage"])
return {"prioridade": r["text"].strip().lower()}
| Parametro | Cosa fa |
|---|---|
prompt |
La domanda. |
system |
L'istruzione di sistema: il ruolo e le regole del modello. |
messages |
Una conversazione, al posto di prompt (vedi Una conversazione). |
model |
Il nome dell'alias. Senza, vale l'alias di testo predefinito. |
max_tokens |
La dimensione massima della risposta. Senza, vale quella dell'alias e poi quella della piattaforma. |
temperature |
Da 0 a 2. Un valore basso dà risposte più prevedibili. Senza, vale quella del modello. |
files |
File che accompagnano la domanda (vedi Inviare file). |
stream |
Un nome, perché il testo appaia sullo schermo di chi ha chiamato mentre il modello lo scrive (vedi Risposte in diretta sullo schermo). |
Il risultato è un dict:
| Chiave | Cosa contiene |
|---|---|
text |
Il testo della risposta. |
stop_reason |
Perché il modello si è fermato: end, max_tokens, tool_use, refusal o other. |
usage |
I token consumati, in input_tokens e output_tokens. |
model, provider, alias |
Chi ha risposto. |
Uno stop_reason uguale a max_tokens vuol dire che la risposta è stata
tagliata. Alza max_tokens o chiedi una risposta più breve.
Una conversazione
Per continuare una conversazione, passa la cronologia in messages, con i
ruoli user e assistant alternati:
from api_manager import ai
def main(input):
r = ai.chat(
messages=[
{"role": "user", "content": "O meu nome é Ana."},
{"role": "assistant", "content": "Olá, Ana!"},
{"role": "user", "content": "Como me chamo?"},
],
)
return {"resposta": r["text"]}
Con messages e prompt insieme, il prompt entra come ultimo messaggio
dell'utente. La lista può anche andare come primo argomento, senza messages=:
ai.chat([...]).
Chiedere JSON con una forma precisa
ai.json chiede la risposta in JSON, la valida rispetto a un JSON Schema e
restituisce il JSON già letto:
from api_manager import ai
ESQUEMA = {
"type": "object",
"properties": {
"nif": {"type": "string", "description": "NIF do cliente, 9 algarismos"},
"total": {"type": "number", "description": "Total com IVA, em euros"},
},
"required": ["nif", "total"],
}
def main(input):
factura = ai.json(
"Extrai o NIF do cliente e o total desta factura.",
schema=ESQUEMA,
files=[input["args"]["factura"]],
)
return factura # {"nif": "...", "total": 123.45}
- Lo schema descrive la forma: i tipi, i campi obbligatori e una
descriptionper ogni campo. Migliore è la descrizione, migliore è la risposta. - Una risposta che non rispetta lo schema dà l'errore
invalid_output. Lo script non riceve mai dati con la forma sbagliata. - I fornitori che supportano l'output strutturato ricevono lo schema nella richiesta. Gli altri lo ricevono nell'istruzione di sistema, e la risposta viene validata comunque.
Inviare file
files= invia file dell'app con la richiesta, in ai.chat e in ai.json.
Accetta gli argomenti di tipo Upload così come arrivano in
input["args"], oppure ciò che restituisce files.store:
from api_manager import ai, files
def main(input):
# un argomento di tipo Upload di un'API
foto = input["args"]["foto"]
estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])
# un file creato dallo script stesso
vendas = files.store(b"produto;quantidade\nCadeira;12\nMesa;30\n", "vendas.csv", "text/csv")
melhor = ai.chat("Que produto vendeu mais? Responde só com o nome.", files=[vendas])
return {"estado": estado["text"], "mais_vendido": melhor["text"]}
| Tipo | Come viene inviato |
|---|---|
| Immagini PNG, JPEG, GIF e WebP | Come immagine, per i modelli che vedono le immagini. |
| Come documento, per i modelli che leggono i PDF. | |
| Testo (txt, csv, json, md, xml e yaml) | Come testo, prima della domanda. |
Ogni file può arrivare a 20 MB, e una richiesta a 40 MB. Un modello solo
testuale rifiuta immagini e PDF con l'errore invalid_request.
Embeddings
ai.embed trasforma il testo in vettori, per cercare per significato e non
solo per parole uguali:
from api_manager import ai
def semelhanca(a, b):
produto = sum(x * y for x, y in zip(a, b))
normas = (sum(x * x for x in a) ** 0.5) * (sum(y * y for y in b) ** 0.5)
return produto / normas
def main(input):
pergunta = ai.embed(input["args"]["pergunta"]) # un vettore
artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
vectores = ai.embed(artigos) # un vettore por texto
melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
return {"artigo": artigos[melhor]}
Un testo restituisce un vettore. Una lista restituisce una lista di vettori,
nello stesso ordine, fino a 2048 testi per chiamata. Senza model=, vale
l'alias di embeddings predefinito.
Gli alias dell'app
ai.models() restituisce gli alias dell'app, ciascuno con il nome, l'uso,
il segno di predefinito, il fornitore e il modello. Serve a uno script per
scegliere il modello durante l'esecuzione o per spiegare perché manca un
alias.
Errori
Una chiamata che fallisce solleva ai.Error. L'attributo code è uguale
per tutti i fornitori, e il messaggio dice cosa è successo:
from api_manager import ai, log
def main(input):
try:
r = ai.chat(input["args"]["pergunta"])
except ai.Error as e:
log("IA:", e.code, str(e))
if e.code in ("rate_limited", "unavailable", "timeout", "connection"):
return {"tentar_mais_tarde": True}
raise
return {"resposta": r["text"]}
| Codice | Cosa vuol dire |
|---|---|
not_configured |
Manca l'alias, il fornitore è disattivato o il modello non è più autorizzato. |
rate_limited |
Il fornitore ha rifiutato per troppe richieste. |
timeout |
Il fornitore non ha risposto entro il tempo massimo. |
unavailable, connection |
Il fornitore è fuori servizio o non è raggiungibile. |
auth, permission |
La chiave è stata rifiutata o non ha il permesso. |
invalid_request |
La richiesta non è valida per questo fornitore o modello. |
invalid_output |
Il JSON della risposta non rispetta lo schema. |
refused |
Il modello si è rifiutato di rispondere. |
not_supported |
Il fornitore non fa questa operazione, oppure il file è di un tipo che non si può inviare. |
cancelled |
L'esecuzione è finita prima della risposta. |
max_steps |
ai.run ha raggiunto il massimo di passi senza una risposta finale. |
not_found, unknown |
Il modello o l'indirizzo non esiste, oppure è successo un altro errore. |
Limite di tempo e log
- Una risposta può richiedere decine di secondi. Il Limite di tempo dello script deve bastare per tutte le chiamate: in uno script con più chiamate, alzalo.
- Quando l'esecuzione finisce, per il limite di tempo o per un annullamento, le richieste ancora in attesa vengono annullate presso il fornitore.
- Ogni chiamata scrive una riga nei log dell'esecuzione, con l'alias, il modello
e la durata, per esempio
[ai] texto (local/qwen2.5:0.5b): 1840 ms. - La piattaforma non conserva il testo delle richieste né delle risposte, a meno che l'app non attivi il debug (vedi Modelli di IA dell'app). La richiesta va al fornitore di IA dell'app, quindi non inviargli dati personali senza necessità.
Domande frequenti
Posso usare l'IA da un widget o dal browser? No. L'IA esiste solo negli script, che girano sul server, e così le chiavi non arrivano mai al browser. Una schermata che ha bisogno di IA chiama un'API che esegue uno script.
Lo script dice not_configured e l'alias esiste. Controlla che l'alias
sia dell'uso giusto (un alias di embeddings non serve per ai.chat), che il
fornitore sia attivo e che il modello sia ancora autorizzato.
Posso usare direttamente la libreria di OpenAI o di Anthropic? Puoi
installarla dal pannello pip, ma la chiave dovrebbe stare in un segreto
dell'app, e lo script perderebbe gli alias e i codici di
errore comuni. Il modulo ai esiste per questo.