KEPLIN Docs

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