Använda AI i skript
Be appens AI-modeller om text, JSON med en bestämd form och embeddings, skicka filer, hantera fel och veta vad varje leverantör gör.
Appens skript anropar AI med SDK:ns modul ai. Skriptet väljer modell via
aliasets namn, och förfrågan går ut från plattformens server med
leverantörens autentiseringsuppgifter. Skriptet ser aldrig nycklarna.
from api_manager import ai
def main(input):
r = ai.chat("Resume em três frases: " + input["args"]["texto"])
return {"resumo": r["text"]}
Innan du börjar
- Tenanten måste ha en aktiv AI-leverantör med tillåtna modeller. Se AI-leverantörer.
- Appen måste ha ett alias för varje användning som skriptet begär. Utan
model=använder skriptet standardaliaset för den användningen. Se Appens AI-modeller.
Vad varje leverantör gör
| Leverantör | Text, JSON och verktyg | Inbäddningar | Bilder | Transkribering | Tal | Batcher |
|---|---|---|---|---|---|---|
| OpenAI | Ja | Ja | Ja | Ja | Ja | Ja |
| Anthropic | Ja | Nej | Nej | Nej | Nej | Ja |
| Microsoft Foundry | Ja | Ja | Ja | Ja | Ja | Nej |
| Amazon Bedrock | Ja | Titan och Cohere | Nova Canvas, Titan och Stability | Nej | Nej | Nej |
| Google Cloud | Ja | Ja | Ja | Ja | Ja | Bara via Gemini API |
| OpenRouter | Ja | Ja | Ja | Nej | Nej | Nej |
| OpenAI-kompatibel | Ja | Beror på servern | Beror på servern | Beror på servern | Beror på servern | Nej |
Hos en leverantör som inte gör en åtgärd ger anropet felet not_supported.
Hos alla leverantörer fungerar åtgärden bara med en modell som gör den: en
textmodell skapar inga bilder.
Verktygen och batcherna finns i Verktyg och batcher, och bilderna, transkriberingen och talet i Bilder och ljud.
Be om text
ai.chat skickar en förfrågan och returnerar modellens svar:
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 | Vad den gör |
|---|---|
prompt |
Frågan. |
system |
Systeminstruktionen: modellens roll och regler. |
messages |
En konversation, i stället för prompt (se En konversation). |
model |
Aliasets namn. Utan den gäller standardaliaset för text. |
max_tokens |
Svarets maximala längd. Utan den gäller aliasets värde och sedan plattformens. |
temperature |
Från 0 till 2. Ett lågt värde ger mer förutsägbara svar. Utan den gäller modellens värde. |
files |
Filer som följer med frågan (se Skicka filer). |
stream |
Ett namn, så att texten visas på skärmen hos den som anropade medan modellen skriver den (se Svar i realtid på skärmen). |
Resultatet är en dict:
| Nyckel | Vad den innehåller |
|---|---|
text |
Svarets text. |
stop_reason |
Varför modellen slutade: end, max_tokens, tool_use, refusal eller other. |
usage |
De förbrukade tokens, i input_tokens och output_tokens. |
model, provider, alias |
Vem som svarade. |
En stop_reason som är max_tokens betyder att svaret klipptes av. Höj
max_tokens eller be om ett kortare svar.
En konversation
För att fortsätta en konversation skickar du historiken i messages, med
rollerna user och assistant om vartannat:
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 och prompt läggs prompt till som användarens sista
meddelande. Listan kan också skickas som första argument, utan messages=:
ai.chat([...]).
Be om JSON med en bestämd form
ai.json ber om svaret i JSON, validerar det mot ett JSON Schema och
returnerar den redan inlästa JSON-datan:
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}
- Schemat beskriver formen: typerna, de obligatoriska fälten och en
descriptionför varje fält. Ju bättre beskrivning, desto bättre svar. - Ett svar som inte följer schemat ger felet
invalid_output. Skriptet får aldrig data med fel form. - Leverantörer som stöder strukturerad utdata får schemat i förfrågan. De andra får det i systeminstruktionen, och svaret valideras ändå.
Skicka filer
files= skickar appens filer med förfrågan, i ai.chat och i ai.json.
Den tar emot argument av typen Upload precis som de kommer i
input["args"], eller det som files.store returnerar:
from api_manager import ai, files
def main(input):
# ett argument av typen Upload i ett API
foto = input["args"]["foto"]
estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])
# en fil som skriptet själv skapar
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"]}
| Typ | Hur den skickas |
|---|---|
| Bilder i PNG, JPEG, GIF och WebP | Som bild, för modeller som ser bilder. |
| Som dokument, för modeller som läser PDF. | |
| Text (txt, csv, json, md, xml och yaml) | Som text, före frågan. |
Varje fil får vara upp till 20 MB, och en förfrågan upp till 40 MB. En
modell som bara hanterar text avvisar bilder och PDF med felet
invalid_request.
Embeddings
ai.embed gör om text till vektorer, så att du kan söka på betydelse och
inte bara på samma 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"]) # en vektor
artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
vectores = ai.embed(artigos) # en vektor por texto
melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
return {"artigo": artigos[melhor]}
En text returnerar en vektor. En lista returnerar en lista med vektorer, i
samma ordning, upp till 2048 texter per anrop. Utan model= gäller
standardaliaset för embeddings.
Appens alias
ai.models() returnerar appens alias, vart och ett med namn, användning,
standardmarkering, leverantör och modell. Ett skript kan använda det för att
välja modell under körningen eller för att förklara varför ett alias saknas.
Fel
Ett anrop som misslyckas kastar ai.Error. Attributet code är detsamma
för alla leverantörer, och meddelandet säger vad som hände:
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"]}
| Kod | Vad den betyder |
|---|---|
not_configured |
Aliaset saknas, leverantören är inaktiverad eller modellen är inte längre tillåten. |
rate_limited |
Leverantören avvisade på grund av för många förfrågningar. |
timeout |
Leverantören svarade inte inom den maximala tiden. |
unavailable, connection |
Leverantören är nere eller gick inte att nå. |
auth, permission |
Nyckeln avvisades eller saknar behörighet. |
invalid_request |
Förfrågan är inte giltig för den här leverantören eller modellen. |
invalid_output |
Svarets JSON följer inte schemat. |
refused |
Modellen vägrade svara. |
not_supported |
Leverantören gör inte den här åtgärden, eller filen är av en typ som inte kan skickas. |
cancelled |
Körningen slutade före svaret. |
max_steps |
ai.run nådde det maximala antalet steg utan slutligt svar. |
not_found, unknown |
Modellen eller adressen finns inte, eller så inträffade ett annat fel. |
Tidsgräns och loggar
- Ett svar kan ta tiotals sekunder. Skriptets Tidsgräns måste räcka för alla anrop: höj den i ett skript med flera anrop.
- När körningen slutar, på grund av tidsgränsen eller en avbrytning, avbryts de förfrågningar som fortfarande väntar hos leverantören.
- Varje anrop skriver en rad i körningens loggar, med aliaset, modellen och
tiden, till exempel
[ai] texto (local/qwen2.5:0.5b): 1840 ms. - Plattformen sparar inte texten i förfrågningarna eller svaren, om inte appen slår på felsökningen (se Appens AI-modeller). Förfrågan går till appens AI-leverantör, så skicka inte personuppgifter dit i onödan.
Vanliga frågor
Kan jag använda AI från en widget eller från webbläsaren? Nej. AI finns bara i skripten, som körs på servern, så nycklarna når aldrig webbläsaren. En skärm som behöver AI anropar ett API som kör ett skript.
Skriptet säger not_configured fast aliaset finns. Kontrollera att
aliaset har rätt användning (ett alias för embeddings fungerar inte för
ai.chat), att leverantören är aktiv och att modellen fortfarande är
tillåten där.
Kan jag använda OpenAI:s eller Anthropics bibliotek direkt? Du kan
installera det via panelen pip, men då måste nyckeln ligga i en
hemlighet i appen, och skriptet förlorar aliasen och de
gemensamma felkoderna. Det är därför modulen ai finns.