AI gebruiken in scripts
Tekst, JSON met een vaste vorm en embeddings vragen aan de AI-modellen van de app, bestanden meesturen, fouten afhandelen en weten wat elke provider doet.
De scripts van de app roepen AI aan via de module ai van de SDK. Het script
kiest het model via de naam van de alias, en het verzoek vertrekt vanaf de
server van het platform met de inloggegevens van de provider. Het script ziet
de sleutels nooit.
from api_manager import ai
def main(input):
r = ai.chat("Resume em três frases: " + input["args"]["texto"])
return {"resumo": r["text"]}
Voordat u begint
- De tenant moet een actieve AI-provider hebben, met toegestane modellen. Zie AI-providers.
- De app moet een alias hebben voor elk gebruik dat het script vraagt. Zonder
model=gebruikt het script de standaardalias van dat gebruik. Zie AI-modellen van de app.
Wat elke provider doet
| Provider | Tekst, JSON en tools | Embeddings | Afbeeldingen | Transcriptie | Spraak | Batches |
|---|---|---|---|---|---|---|
| OpenAI | Ja | Ja | Ja | Ja | Ja | Ja |
| Anthropic | Ja | Nee | Nee | Nee | Nee | Ja |
| Microsoft Foundry | Ja | Ja | Ja | Ja | Ja | Nee |
| Amazon Bedrock | Ja | Titan en Cohere | Nova Canvas, Titan en Stability | Nee | Nee | Nee |
| Google Cloud | Ja | Ja | Ja | Ja | Ja | Alleen via de Gemini API |
| OpenRouter | Ja | Ja | Ja | Nee | Nee | Nee |
| OpenAI-compatibel | Ja | Afhankelijk van de server | Afhankelijk van de server | Afhankelijk van de server | Afhankelijk van de server | Nee |
Bij een provider die een bewerking niet doet, geeft de aanroep de fout
not_supported. Bij elke provider werkt de bewerking alleen met een model dat
haar doet: een tekstmodel genereert geen afbeeldingen.
De tools en de batches staan in Tools en batches, en de afbeeldingen, de transcriptie en de spraak in Afbeeldingen en audio.
Tekst vragen
ai.chat stuurt een verzoek en geeft het antwoord van het model terug:
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()}
| Parameter | Wat die doet |
|---|---|
prompt |
De vraag. |
system |
De systeeminstructie: de rol en de regels van het model. |
messages |
Een gesprek, in plaats van prompt (zie Een gesprek). |
model |
De naam van de alias. Zonder deze geldt de standaardalias voor tekst. |
max_tokens |
De maximale lengte van het antwoord. Zonder deze geldt de waarde van de alias en daarna die van het platform. |
temperature |
Van 0 tot 2. Een lage waarde geeft voorspelbaardere antwoorden. Zonder deze geldt de waarde van het model. |
files |
Bestanden die met de vraag meegaan (zie Bestanden meesturen). |
stream |
Een naam, zodat de tekst op het scherm verschijnt van wie aanriep terwijl het model hem schrijft (zie Live antwoorden op het scherm). |
Het resultaat is een dict:
| Sleutel | Wat die bevat |
|---|---|
text |
De tekst van het antwoord. |
stop_reason |
Waarom het model stopte: end, max_tokens, tool_use, refusal of other. |
usage |
De verbruikte tokens, in input_tokens en output_tokens. |
model, provider, alias |
Wie antwoordde. |
Een stop_reason gelijk aan max_tokens betekent dat het antwoord is
afgekapt. Verhoog max_tokens of vraag om een korter antwoord.
Een gesprek
Om een gesprek voort te zetten, geeft u de geschiedenis mee in messages,
met de rollen user en assistant om en om:
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"]}
Met messages en prompt tegelijk komt de prompt erbij als het laatste
bericht van de gebruiker. De lijst kan ook als eerste argument worden meegegeven, zonder messages=:
ai.chat([...]).
JSON met een vaste vorm vragen
ai.json vraagt het antwoord in JSON, valideert het tegen een JSON Schema
en geeft de al gelezen JSON terug:
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}
- Het schema beschrijft de vorm: de typen, de verplichte velden en een
descriptionbij elk veld. Hoe beter de beschrijving, hoe beter het antwoord. - Een antwoord dat niet aan het schema voldoet, geeft de fout
invalid_output. Het script krijgt nooit gegevens met de verkeerde vorm. - Providers die gestructureerde uitvoer ondersteunen, krijgen het schema in het verzoek. De andere krijgen het in de systeeminstructie, en het antwoord wordt toch gevalideerd.
Bestanden meesturen
files= stuurt bestanden van de app mee met het verzoek, in ai.chat en
in ai.json. Het accepteert argumenten van het type Upload zoals ze in
input["args"] binnenkomen, of wat files.store teruggeeft:
from api_manager import ai, files
def main(input):
# een argument van het type Upload van een API
foto = input["args"]["foto"]
estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])
# een bestand dat het script zelf maakt
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"]}
| Type | Hoe het meegaat |
|---|---|
| Afbeeldingen PNG, JPEG, GIF en WebP | Als afbeelding, voor modellen die afbeeldingen zien. |
| Als document, voor modellen die pdf lezen. | |
| Tekst (txt, csv, json, md, xml en yaml) | Als tekst, vóór de vraag. |
Elk bestand mag tot 20 MB groot zijn, en een verzoek tot 40 MB. Een model
dat alleen tekst kent, weigert afbeeldingen en pdf met de fout
invalid_request.
Embeddings
ai.embed zet tekst om in vectoren, om op betekenis te zoeken en niet
alleen op gelijke woorden:
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"]) # één vector
artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
vectores = ai.embed(artigos) # één vector por texto
melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
return {"artigo": artigos[melhor]}
Eén tekst geeft één vector terug. Een lijst geeft een lijst vectoren terug,
in dezelfde volgorde, tot 2048 teksten per aanroep. Zonder model= geldt de
standaardalias voor embeddings.
De aliassen van de app
ai.models() geeft de aliassen van de app terug, elk met de naam, het
gebruik, de standaardmarkering, de provider en het model. Een script kan het
gebruiken om tijdens de uitvoering het model te kiezen of om uit te leggen
waarom een alias ontbreekt.
Fouten
Een aanroep die mislukt, gooit ai.Error. Het attribuut code is bij alle
providers gelijk, en het bericht zegt wat er gebeurde:
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"]}
| Code | Wat die betekent |
|---|---|
not_configured |
De alias ontbreekt, de provider is uitgeschakeld of het model is niet meer toegestaan. |
rate_limited |
De provider weigerde wegens te veel verzoeken. |
timeout |
De provider antwoordde niet binnen de maximale tijd. |
unavailable, connection |
De provider is niet beschikbaar of niet bereikbaar. |
auth, permission |
De sleutel werd geweigerd of heeft geen toestemming. |
invalid_request |
Het verzoek is niet geldig voor deze provider of dit model. |
invalid_output |
De JSON van het antwoord voldoet niet aan het schema. |
refused |
Het model weigerde te antwoorden. |
not_supported |
De provider doet deze bewerking niet, of het bestand is van een type dat niet meegaat. |
cancelled |
De uitvoering stopte vóór het antwoord. |
max_steps |
ai.run bereikte het maximum aantal stappen zonder definitief antwoord. |
not_found, unknown |
Het model of het adres bestaat niet, of er gebeurde een andere fout. |
Tijdslimiet en logs
- Een antwoord kan tientallen seconden duren. De Tijdslimiet van het script moet genoeg zijn voor alle aanroepen: verhoog die in een script met meerdere aanroepen.
- Wanneer de uitvoering stopt, door de tijdslimiet of een annulering, worden de verzoeken die nog wachten bij de provider geannuleerd.
- Elke aanroep schrijft een regel in de logs van de uitvoering, met de alias,
het model en de duur, bijvoorbeeld
[ai] texto (local/qwen2.5:0.5b): 1840 ms. - Het platform bewaart de tekst van de verzoeken en de antwoorden niet, tenzij de app het debuggen aanzet (zie AI-modellen van de app). Het verzoek gaat naar de AI-provider van de app, stuur er dus geen persoonsgegevens heen zonder dat het nodig is.
Veelgestelde vragen
Kan ik AI gebruiken vanuit een widget of vanuit de browser? Nee. AI bestaat alleen in de scripts, die op de server draaien, zodat de sleutels nooit in de browser komen. Een scherm dat AI nodig heeft, roept een API aan die een script uitvoert.
Het script meldt not_configured en de alias bestaat. Controleer of de
alias het juiste gebruik heeft (een alias voor embeddings werkt niet voor
ai.chat), of de provider actief is en of het model er nog toegestaan is.
Kan ik de bibliotheek van OpenAI of Anthropic rechtstreeks gebruiken? U
kunt die installeren via het paneel pip, maar dan moet de sleutel in een
secret van de app staan, en het script verliest de aliassen en de
gemeenschappelijke foutcodes. Daarvoor bestaat de module ai.