KEPLIN Docs

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 description per 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.
PDF 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.