KEPLIN Docs

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 description fü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.
PDF 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.