KI in Skripten verwenden
Text, JSON in einer festen Form und Embeddings von den KI-Modellen der App anfordern, Dateien senden, Fehler behandeln und wissen, was jeder Anbieter kann.
Die Skripte der App rufen die KI über das Modul ai des SDK auf. Das Skript
wählt das Modell über den Namen des Alias, und die Anfrage geht vom Server der
Plattform mit den Zugangsdaten des Anbieters hinaus. Das Skript sieht die
Schlüssel nie.
from api_manager import ai
def main(input):
r = ai.chat("Resume em três frases: " + input["args"]["texto"])
return {"resumo": r["text"]}
Bevor Sie beginnen
- Der Mandant braucht einen aktiven KI-Anbieter mit zugelassenen Modellen. Siehe KI-Anbieter.
- Die App braucht einen Alias für jede Verwendung, die das Skript anfordert.
Ohne
model=nutzt das Skript den Standard-Alias dieser Verwendung. Siehe KI-Modelle der App.
Was jeder Anbieter kann
| Anbieter | Text, JSON und Werkzeuge | Embeddings | Bilder | Transkription | Sprache | Batches |
|---|---|---|---|---|---|---|
| OpenAI | Ja | Ja | Ja | Ja | Ja | Ja |
| Anthropic | Ja | Nein | Nein | Nein | Nein | Ja |
| Microsoft Foundry | Ja | Ja | Ja | Ja | Ja | Nein |
| Amazon Bedrock | Ja | Titan und Cohere | Nova Canvas, Titan und Stability | Nein | Nein | Nein |
| Google Cloud | Ja | Ja | Ja | Ja | Ja | Nur über die Gemini API |
| OpenRouter | Ja | Ja | Ja | Nein | Nein | Nein |
| OpenAI-kompatibel | Ja | Je nach Server | Je nach Server | Je nach Server | Je nach Server | Nein |
Bei einem Anbieter, der eine Operation nicht anbietet, gibt der Aufruf den
Fehler not_supported. Bei jedem Anbieter funktioniert die Operation nur mit
einem Modell, das sie beherrscht: Ein Textmodell erzeugt keine Bilder.
Die Werkzeuge und die Batches stehen unter Werkzeuge und Batches, die Bilder, die Transkription und die Sprache unter Bilder und Audio.
Text anfordern
ai.chat sendet eine Anfrage und gibt die Antwort des Modells zurück:
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 | Was er bewirkt |
|---|---|
prompt |
Die Frage. |
system |
Die Systemanweisung: Rolle und Regeln des Modells. |
messages |
Ein Gespräch, statt prompt (siehe Ein Gespräch). |
model |
Der Name des Alias. Ohne ihn gilt der Standard-Alias für Text. |
max_tokens |
Die maximale Länge der Antwort. Ohne ihn gilt der Wert des Alias und danach der der Plattform. |
temperature |
Von 0 bis 2. Ein niedriger Wert gibt vorhersehbarere Antworten. Ohne ihn gilt der Wert des Modells. |
files |
Dateien, die mit der Frage mitgehen (siehe Dateien senden). |
stream |
Ein Name, damit der Text auf dem Bildschirm der aufrufenden Person erscheint, während das Modell ihn schreibt (siehe Live-Antworten auf dem Bildschirm). |
Das Ergebnis ist ein Dict:
| Schlüssel | Was er enthält |
|---|---|
text |
Den Text der Antwort. |
stop_reason |
Warum das Modell aufgehört hat: end, max_tokens, tool_use, refusal oder other. |
usage |
Die verbrauchten Tokens, in input_tokens und output_tokens. |
model, provider, alias |
Wer geantwortet hat. |
Ein stop_reason gleich max_tokens bedeutet, dass die Antwort abgeschnitten
wurde. Erhöhen Sie max_tokens oder fordern Sie eine kürzere Antwort an.
Ein Gespräch
Um ein Gespräch fortzusetzen, übergeben Sie den Verlauf in messages, mit
den Rollen user und assistant im Wechsel:
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"]}
Mit messages und prompt zugleich kommt der prompt als letzte Nachricht
des Benutzers hinzu. Die Liste kann auch als erstes Argument übergeben werden, ohne messages=:
ai.chat([...]).
JSON in einer festen Form anfordern
ai.json fordert die Antwort als JSON an, prüft sie gegen ein JSON Schema
und gibt das bereits gelesene JSON zurück:
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}
- Das Schema beschreibt die Form: die Typen, die Pflichtfelder und eine
descriptionfür jedes Feld. Je besser die Beschreibung, desto besser die Antwort. - Eine Antwort, die das Schema nicht erfüllt, gibt den Fehler
invalid_output. Das Skript erhält nie Daten in der falschen Form. - Anbieter, die strukturierte Ausgabe unterstützen, erhalten das Schema in der Anfrage. Die anderen erhalten es in der Systemanweisung, und die Antwort wird trotzdem geprüft.
Dateien senden
files= schickt Dateien der App mit der Anfrage, in ai.chat und in
ai.json. Es nimmt Argumente vom Typ Upload so an, wie sie in
input["args"] ankommen, oder das, was files.store zurückgibt:
from api_manager import ai, files
def main(input):
# ein Argument vom Typ Upload einer API
foto = input["args"]["foto"]
estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])
# eine Datei, die das Skript selbst erstellt
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 | Wie er gesendet wird |
|---|---|
| Bilder PNG, JPEG, GIF und WebP | Als Bild, für Modelle, die Bilder sehen. |
| Als Dokument, für Modelle, die PDF lesen. | |
| Text (txt, csv, json, md, xml und yaml) | Als Text, vor der Frage. |
Jede Datei darf bis zu 20 MB groß sein, eine Anfrage bis zu 40 MB. Ein
reines Textmodell lehnt Bilder und PDF mit dem Fehler invalid_request ab.
Embeddings
ai.embed verwandelt Text in Vektoren, um nach Bedeutung zu suchen und
nicht nur nach gleichen Wörtern:
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"]) # ein Vektor
artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
vectores = ai.embed(artigos) # ein Vektor por texto
melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
return {"artigo": artigos[melhor]}
Ein Text gibt einen Vektor zurück. Eine Liste gibt eine Liste von Vektoren
zurück, in derselben Reihenfolge, bis zu 2048 Texte pro Aufruf. Ohne
model= gilt der Standard-Alias für Embeddings.
Die Aliase der App
ai.models() gibt die Aliase der App zurück, jeweils mit Name, Verwendung,
Standard-Markierung, Anbieter und Modell. Ein Skript kann damit das Modell
während der Ausführung wählen oder erklären, warum ein Alias fehlt.
Fehler
Ein Aufruf, der fehlschlägt, löst ai.Error aus. Das Attribut code ist
bei allen Anbietern gleich, und die Meldung sagt, was passiert ist:
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 | Was er bedeutet |
|---|---|
not_configured |
Der Alias fehlt, der Anbieter ist deaktiviert oder das Modell ist nicht mehr freigegeben. |
rate_limited |
Der Anbieter hat wegen zu vieler Anfragen abgelehnt. |
timeout |
Der Anbieter hat nicht innerhalb der maximalen Zeit geantwortet. |
unavailable, connection |
Der Anbieter ist nicht verfügbar oder nicht erreichbar. |
auth, permission |
Der Schlüssel wurde abgelehnt oder hat keine Berechtigung. |
invalid_request |
Die Anfrage ist für diesen Anbieter oder dieses Modell nicht gültig. |
invalid_output |
Das JSON der Antwort erfüllt das Schema nicht. |
refused |
Das Modell hat die Antwort verweigert. |
not_supported |
Der Anbieter bietet diese Operation nicht an, oder die Datei hat einen Typ, der nicht gesendet wird. |
cancelled |
Die Ausführung endete vor der Antwort. |
max_steps |
ai.run hat die maximale Anzahl Schritte ohne endgültige Antwort erreicht. |
not_found, unknown |
Das Modell oder die Adresse existiert nicht, oder ein anderer Fehler ist aufgetreten. |
Zeitlimit und Logs
- Eine Antwort kann Dutzende Sekunden dauern. Das Zeitlimit des Skripts muss für alle Aufrufe reichen: Erhöhen Sie es in einem Skript mit mehreren Aufrufen.
- Wenn die Ausführung endet, durch das Zeitlimit oder einen Abbruch, werden die noch wartenden Anfragen beim Anbieter abgebrochen.
- Jeder Aufruf schreibt eine Zeile in die Logs der Ausführung, mit Alias, Modell
und Dauer, zum Beispiel
[ai] texto (local/qwen2.5:0.5b): 1840 ms. - Die Plattform speichert den Text der Anfragen und Antworten nicht, außer die App schaltet die Fehlersuche ein (siehe KI-Modelle der App). Die Anfrage geht an den KI-Anbieter der App, senden Sie ihm also keine personenbezogenen Daten ohne Not.
Häufige Fragen
Kann ich die KI aus einem Widget oder aus dem Browser nutzen? Nein. Die KI gibt es nur in den Skripten, die auf dem Server laufen, und so gelangen die Schlüssel nie in den Browser. Ein Bildschirm, der KI braucht, ruft eine API auf, die ein Skript ausführt.
Das Skript meldet not_configured, obwohl der Alias existiert. Prüfen
Sie, ob der Alias die richtige Verwendung hat (ein Alias für Embeddings dient
nicht für ai.chat), ob der Anbieter aktiv ist und ob das Modell dort noch
freigegeben ist.
Kann ich die Bibliothek von OpenAI oder Anthropic direkt verwenden? Sie
können sie über das Panel pip installieren, aber der Schlüssel müsste
dann in einem Secret der App liegen, und das Skript verlöre die Aliase und die
einheitlichen Fehlercodes. Dafür gibt es das Modul ai.