KEPLIN Docs

AI gebruiken in scripts

Tekst, JSON met een vaste vorm en embeddings vragen aan de AI-modellen van de app, bestanden meesturen, fouten afhandelen en weten wat elke provider doet.

De scripts van de app roepen AI aan via de module ai van de SDK. Het script kiest het model via de naam van de alias, en het verzoek vertrekt vanaf de server van het platform met de inloggegevens van de provider. Het script ziet de sleutels nooit.

from api_manager import ai


def main(input):
    r = ai.chat("Resume em três frases: " + input["args"]["texto"])
    return {"resumo": r["text"]}

Voordat u begint

  • De tenant moet een actieve AI-provider hebben, met toegestane modellen. Zie AI-providers.
  • De app moet een alias hebben voor elk gebruik dat het script vraagt. Zonder model= gebruikt het script de standaardalias van dat gebruik. Zie AI-modellen van de app.

Wat elke provider doet

Provider Tekst, JSON en tools Embeddings Afbeeldingen Transcriptie Spraak Batches
OpenAI Ja Ja Ja Ja Ja Ja
Anthropic Ja Nee Nee Nee Nee Ja
Microsoft Foundry Ja Ja Ja Ja Ja Nee
Amazon Bedrock Ja Titan en Cohere Nova Canvas, Titan en Stability Nee Nee Nee
Google Cloud Ja Ja Ja Ja Ja Alleen via de Gemini API
OpenRouter Ja Ja Ja Nee Nee Nee
OpenAI-compatibel Ja Afhankelijk van de server Afhankelijk van de server Afhankelijk van de server Afhankelijk van de server Nee

Bij een provider die een bewerking niet doet, geeft de aanroep de fout not_supported. Bij elke provider werkt de bewerking alleen met een model dat haar doet: een tekstmodel genereert geen afbeeldingen.

De tools en de batches staan in Tools en batches, en de afbeeldingen, de transcriptie en de spraak in Afbeeldingen en audio.

Tekst vragen

ai.chat stuurt een verzoek en geeft het antwoord van het model terug:

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 Wat die doet
prompt De vraag.
system De systeeminstructie: de rol en de regels van het model.
messages Een gesprek, in plaats van prompt (zie Een gesprek).
model De naam van de alias. Zonder deze geldt de standaardalias voor tekst.
max_tokens De maximale lengte van het antwoord. Zonder deze geldt de waarde van de alias en daarna die van het platform.
temperature Van 0 tot 2. Een lage waarde geeft voorspelbaardere antwoorden. Zonder deze geldt de waarde van het model.
files Bestanden die met de vraag meegaan (zie Bestanden meesturen).
stream Een naam, zodat de tekst op het scherm verschijnt van wie aanriep terwijl het model hem schrijft (zie Live antwoorden op het scherm).

Het resultaat is een dict:

Sleutel Wat die bevat
text De tekst van het antwoord.
stop_reason Waarom het model stopte: end, max_tokens, tool_use, refusal of other.
usage De verbruikte tokens, in input_tokens en output_tokens.
model, provider, alias Wie antwoordde.

Een stop_reason gelijk aan max_tokens betekent dat het antwoord is afgekapt. Verhoog max_tokens of vraag om een korter antwoord.

Een gesprek

Om een gesprek voort te zetten, geeft u de geschiedenis mee in messages, met de rollen user en assistant om en om:

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"]}

Met messages en prompt tegelijk komt de prompt erbij als het laatste bericht van de gebruiker. De lijst kan ook als eerste argument worden meegegeven, zonder messages=: ai.chat([...]).

JSON met een vaste vorm vragen

ai.json vraagt het antwoord in JSON, valideert het tegen een JSON Schema en geeft de al gelezen JSON terug:

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}
  • Het schema beschrijft de vorm: de typen, de verplichte velden en een description bij elk veld. Hoe beter de beschrijving, hoe beter het antwoord.
  • Een antwoord dat niet aan het schema voldoet, geeft de fout invalid_output. Het script krijgt nooit gegevens met de verkeerde vorm.
  • Providers die gestructureerde uitvoer ondersteunen, krijgen het schema in het verzoek. De andere krijgen het in de systeeminstructie, en het antwoord wordt toch gevalideerd.

Bestanden meesturen

files= stuurt bestanden van de app mee met het verzoek, in ai.chat en in ai.json. Het accepteert argumenten van het type Upload zoals ze in input["args"] binnenkomen, of wat files.store teruggeeft:

from api_manager import ai, files


def main(input):
    # een argument van het type Upload van een API
    foto = input["args"]["foto"]
    estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])

    # een bestand dat het script zelf maakt
    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 Hoe het meegaat
Afbeeldingen PNG, JPEG, GIF en WebP Als afbeelding, voor modellen die afbeeldingen zien.
PDF Als document, voor modellen die pdf lezen.
Tekst (txt, csv, json, md, xml en yaml) Als tekst, vóór de vraag.

Elk bestand mag tot 20 MB groot zijn, en een verzoek tot 40 MB. Een model dat alleen tekst kent, weigert afbeeldingen en pdf met de fout invalid_request.

Embeddings

ai.embed zet tekst om in vectoren, om op betekenis te zoeken en niet alleen op gelijke woorden:

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 vector
    artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
    vectores = ai.embed(artigos)  # één vector por texto
    melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
    return {"artigo": artigos[melhor]}

Eén tekst geeft één vector terug. Een lijst geeft een lijst vectoren terug, in dezelfde volgorde, tot 2048 teksten per aanroep. Zonder model= geldt de standaardalias voor embeddings.

De aliassen van de app

ai.models() geeft de aliassen van de app terug, elk met de naam, het gebruik, de standaardmarkering, de provider en het model. Een script kan het gebruiken om tijdens de uitvoering het model te kiezen of om uit te leggen waarom een alias ontbreekt.

Fouten

Een aanroep die mislukt, gooit ai.Error. Het attribuut code is bij alle providers gelijk, en het bericht zegt wat er gebeurde:

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 Wat die betekent
not_configured De alias ontbreekt, de provider is uitgeschakeld of het model is niet meer toegestaan.
rate_limited De provider weigerde wegens te veel verzoeken.
timeout De provider antwoordde niet binnen de maximale tijd.
unavailable, connection De provider is niet beschikbaar of niet bereikbaar.
auth, permission De sleutel werd geweigerd of heeft geen toestemming.
invalid_request Het verzoek is niet geldig voor deze provider of dit model.
invalid_output De JSON van het antwoord voldoet niet aan het schema.
refused Het model weigerde te antwoorden.
not_supported De provider doet deze bewerking niet, of het bestand is van een type dat niet meegaat.
cancelled De uitvoering stopte vóór het antwoord.
max_steps ai.run bereikte het maximum aantal stappen zonder definitief antwoord.
not_found, unknown Het model of het adres bestaat niet, of er gebeurde een andere fout.

Tijdslimiet en logs

  • Een antwoord kan tientallen seconden duren. De Tijdslimiet van het script moet genoeg zijn voor alle aanroepen: verhoog die in een script met meerdere aanroepen.
  • Wanneer de uitvoering stopt, door de tijdslimiet of een annulering, worden de verzoeken die nog wachten bij de provider geannuleerd.
  • Elke aanroep schrijft een regel in de logs van de uitvoering, met de alias, het model en de duur, bijvoorbeeld [ai] texto (local/qwen2.5:0.5b): 1840 ms.
  • Het platform bewaart de tekst van de verzoeken en de antwoorden niet, tenzij de app het debuggen aanzet (zie AI-modellen van de app). Het verzoek gaat naar de AI-provider van de app, stuur er dus geen persoonsgegevens heen zonder dat het nodig is.

Veelgestelde vragen

Kan ik AI gebruiken vanuit een widget of vanuit de browser? Nee. AI bestaat alleen in de scripts, die op de server draaien, zodat de sleutels nooit in de browser komen. Een scherm dat AI nodig heeft, roept een API aan die een script uitvoert.

Het script meldt not_configured en de alias bestaat. Controleer of de alias het juiste gebruik heeft (een alias voor embeddings werkt niet voor ai.chat), of de provider actief is en of het model er nog toegestaan is.

Kan ik de bibliotheek van OpenAI of Anthropic rechtstreeks gebruiken? U kunt die installeren via het paneel pip, maar dan moet de sleutel in een secret van de app staan, en het script verliest de aliassen en de gemeenschappelijke foutcodes. Daarvoor bestaat de module ai.