Bruke AI i skript
Be AI-modellene i appen om tekst, JSON med en fast form og embeddings, sende filer, håndtere feil og vite hva hver leverandør gjør.
Skriptene i appen kaller AI med modulen ai i SDK-en. Skriptet velger
modellen med navnet på aliaset, og forespørselen går ut fra plattformens
server med leverandørens legitimasjon. Skriptet ser aldri nøklene.
from api_manager import ai
def main(input):
r = ai.chat("Resume em três frases: " + input["args"]["texto"])
return {"resumo": r["text"]}
Før du begynner
- Tenanten må ha en aktiv AI-leverandør med tillatte modeller. Se AI-leverandører.
- Appen må ha et alias for hver bruk skriptet ber om. Uten
model=bruker skriptet standardaliaset for den bruken. Se Appens AI-modeller.
Hva hver leverandør gjør
| Leverandør | Tekst, JSON og verktøy | Innbygginger | Bilder | Transkripsjon | Tale | Batcher |
|---|---|---|---|---|---|---|
| OpenAI | Ja | Ja | Ja | Ja | Ja | Ja |
| Anthropic | Ja | Nei | Nei | Nei | Nei | Ja |
| Microsoft Foundry | Ja | Ja | Ja | Ja | Ja | Nei |
| Amazon Bedrock | Ja | Titan og Cohere | Nova Canvas, Titan og Stability | Nei | Nei | Nei |
| Google Cloud | Ja | Ja | Ja | Ja | Ja | Bare via Gemini API |
| OpenRouter | Ja | Ja | Ja | Nei | Nei | Nei |
| OpenAI-kompatibel | Ja | Avhenger av serveren | Avhenger av serveren | Avhenger av serveren | Avhenger av serveren | Nei |
Hos en leverandør som ikke gjør en operasjon, gir kallet feilen
not_supported. Hos alle leverandører virker operasjonen bare med en modell
som gjør den: en tekstmodell lager ikke bilder.
Verktøyene og batchene står i Verktøy og batcher, og bildene, transkripsjonen og talen i Bilder og lyd.
Be om tekst
ai.chat sender en forespørsel og returnerer svaret fra modellen:
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 | Hva den gjør |
|---|---|
prompt |
Spørsmålet. |
system |
Systeminstruksjonen: modellens rolle og regler. |
messages |
En samtale, i stedet for prompt (se En samtale). |
model |
Navnet på aliaset. Uten den gjelder standardaliaset for tekst. |
max_tokens |
Den største lengden på svaret. Uten den gjelder verdien til aliaset og deretter plattformens. |
temperature |
Fra 0 til 2. En lav verdi gir mer forutsigbare svar. Uten den gjelder modellens verdi. |
files |
Filer som følger med spørsmålet (se Sende filer). |
stream |
Et navn, slik at teksten vises på skjermen til den som kalte mens modellen skriver den (se Svar i sanntid på skjermen). |
Resultatet er en dict:
| Nøkkel | Hva den inneholder |
|---|---|
text |
Teksten i svaret. |
stop_reason |
Hvorfor modellen stoppet: end, max_tokens, tool_use, refusal eller other. |
usage |
Tokens som ble brukt, i input_tokens og output_tokens. |
model, provider, alias |
Hvem som svarte. |
En stop_reason lik max_tokens betyr at svaret ble kuttet. Øk
max_tokens eller be om et kortere svar.
En samtale
For å fortsette en samtale sender du historikken i messages, med rollene
user og assistant annenhver gang:
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"]}
Med både messages og prompt kommer prompt inn som den siste meldingen
fra brukeren. Listen kan også sendes som første argument, uten messages=:
ai.chat([...]).
Be om JSON med en fast form
ai.json ber om svaret i JSON, validerer det mot et JSON Schema og
returnerer JSON-en som allerede er lest:
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}
- Skjemaet beskriver formen: typene, de obligatoriske feltene og en
descriptionfor hvert felt. Jo bedre beskrivelse, jo bedre svar. - Et svar som ikke følger skjemaet, gir feilen
invalid_output. Skriptet får aldri data med feil form. - Leverandører som støtter strukturert utdata, får skjemaet i forespørselen. De andre får det i systeminstruksjonen, og svaret valideres likevel.
Sende filer
files= sender filer fra appen med forespørselen, i ai.chat og i
ai.json. Den tar imot argumenter av typen Upload slik de kommer i
input["args"], eller det files.store returnerer:
from api_manager import ai, files
def main(input):
# et argument av typen Upload i et API
foto = input["args"]["foto"]
estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])
# en fil som skriptet selv lager
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 | Hvordan den sendes |
|---|---|
| Bilder i PNG, JPEG, GIF og WebP | Som bilde, for modeller som ser bilder. |
| Som dokument, for modeller som leser PDF. | |
| Tekst (txt, csv, json, md, xml og yaml) | Som tekst, før spørsmålet. |
Hver fil kan være opptil 20 MB, og en forespørsel opptil 40 MB. En modell
som bare forstår tekst, avviser bilder og PDF med feilen invalid_request.
Embeddings
ai.embed gjør tekst om til vektorer, slik at du kan søke etter mening og
ikke bare etter like ord:
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 vektor
artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
vectores = ai.embed(artigos) # én vektor por texto
melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
return {"artigo": artigos[melhor]}
Én tekst returnerer én vektor. En liste returnerer en liste med vektorer, i
samme rekkefølge, opptil 2048 tekster per kall. Uten model= gjelder
standardaliaset for embeddings.
Aliasene i appen
ai.models() returnerer aliasene i appen, hvert med navn, bruk,
standardmerke, leverandør og modell. Et skript kan bruke det til å velge
modell mens det kjører, eller til å forklare hvorfor et alias mangler.
Feil
Et kall som feiler, kaster ai.Error. Attributtet code er det samme for
alle leverandører, og meldingen sier hva som skjedde:
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"]}
| Kode | Hva den betyr |
|---|---|
not_configured |
Aliaset mangler, leverandøren er deaktivert, eller modellen er ikke lenger tillatt. |
rate_limited |
Leverandøren avviste på grunn av for mange forespørsler. |
timeout |
Leverandøren svarte ikke innen den maksimale tiden. |
unavailable, connection |
Leverandøren er nede eller kunne ikke nås. |
auth, permission |
Nøkkelen ble avvist eller mangler tillatelse. |
invalid_request |
Forespørselen er ikke gyldig for denne leverandøren eller modellen. |
invalid_output |
JSON-en i svaret følger ikke skjemaet. |
refused |
Modellen nektet å svare. |
not_supported |
Leverandøren gjør ikke denne operasjonen, eller filen er av en type som ikke kan sendes. |
cancelled |
Kjøringen sluttet før svaret. |
max_steps |
ai.run nådde det største antallet steg uten endelig svar. |
not_found, unknown |
Modellen eller adressen finnes ikke, eller det skjedde en annen feil. |
Tidsgrense og logger
- Et svar kan ta flere titalls sekunder. Skriptets Tidsgrense må holde for alle kallene: øk den i et skript med flere kall.
- Når kjøringen slutter, på grunn av tidsgrensen eller en avbrytelse, blir forespørslene som fortsatt venter, avbrutt hos leverandøren.
- Hvert kall skriver en linje i loggene for kjøringen, med aliaset, modellen og
varigheten, for eksempel
[ai] texto (local/qwen2.5:0.5b): 1840 ms. - Plattformen lagrer ikke teksten i forespørslene eller svarene, med mindre appen slår på feilsøking (se Appens AI-modeller). Forespørselen går til AI-leverandøren for appen, så ikke send personopplysninger dit uten at det trengs.
Vanlige spørsmål
Kan jeg bruke AI fra en widget eller fra nettleseren? Nei. AI finnes bare i skriptene, som kjører på serveren, så nøklene kommer aldri til nettleseren. En skjerm som trenger AI, kaller et API som kjører et skript.
Skriptet sier not_configured, men aliaset finnes. Sjekk at aliaset har
riktig bruk (et alias for embeddings fungerer ikke for ai.chat), at
leverandøren er aktiv, og at modellen fortsatt er tillatt der.
Kan jeg bruke biblioteket fra OpenAI eller Anthropic direkte? Du kan
installere det fra panelet pip, men da må nøkkelen ligge i en
hemmelighet i appen, og skriptet mister aliasene og de felles
feilkodene. Det er derfor modulen ai finnes.