KEPLIN Docs

Bruke AI i skript

Be AI-modellene i appen om tekst, JSON med en fast form og embeddings, sende filer, håndtere feil og vite hva hver leverandør gjør.

Skriptene i appen kaller AI med modulen ai i SDK-en. Skriptet velger modellen med navnet på aliaset, og forespørselen går ut fra plattformens server med leverandørens legitimasjon. Skriptet ser aldri nøklene.

from api_manager import ai


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

Før du begynner

  • Tenanten må ha en aktiv AI-leverandør med tillatte modeller. Se AI-leverandører.
  • Appen må ha et alias for hver bruk skriptet ber om. Uten model= bruker skriptet standardaliaset for den bruken. Se Appens AI-modeller.

Hva hver leverandør gjør

Leverandør Tekst, JSON og verktøy Innbygginger Bilder Transkripsjon Tale Batcher
OpenAI Ja Ja Ja Ja Ja Ja
Anthropic Ja Nei Nei Nei Nei Ja
Microsoft Foundry Ja Ja Ja Ja Ja Nei
Amazon Bedrock Ja Titan og Cohere Nova Canvas, Titan og Stability Nei Nei Nei
Google Cloud Ja Ja Ja Ja Ja Bare via Gemini API
OpenRouter Ja Ja Ja Nei Nei Nei
OpenAI-kompatibel Ja Avhenger av serveren Avhenger av serveren Avhenger av serveren Avhenger av serveren Nei

Hos en leverandør som ikke gjør en operasjon, gir kallet feilen not_supported. Hos alle leverandører virker operasjonen bare med en modell som gjør den: en tekstmodell lager ikke bilder.

Verktøyene og batchene står i Verktøy og batcher, og bildene, transkripsjonen og talen i Bilder og lyd.

Be om tekst

ai.chat sender en forespørsel og returnerer svaret fra modellen:

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 Hva den gjør
prompt Spørsmålet.
system Systeminstruksjonen: modellens rolle og regler.
messages En samtale, i stedet for prompt (se En samtale).
model Navnet på aliaset. Uten den gjelder standardaliaset for tekst.
max_tokens Den største lengden på svaret. Uten den gjelder verdien til aliaset og deretter plattformens.
temperature Fra 0 til 2. En lav verdi gir mer forutsigbare svar. Uten den gjelder modellens verdi.
files Filer som følger med spørsmålet (se Sende filer).
stream Et navn, slik at teksten vises på skjermen til den som kalte mens modellen skriver den (se Svar i sanntid på skjermen).

Resultatet er en dict:

Nøkkel Hva den inneholder
text Teksten i svaret.
stop_reason Hvorfor modellen stoppet: end, max_tokens, tool_use, refusal eller other.
usage Tokens som ble brukt, i input_tokens og output_tokens.
model, provider, alias Hvem som svarte.

En stop_reason lik max_tokens betyr at svaret ble kuttet. Øk max_tokens eller be om et kortere svar.

En samtale

For å fortsette en samtale sender du historikken i messages, med rollene user og assistant annenhver gang:

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 og prompt kommer prompt inn som den siste meldingen fra brukeren. Listen kan også sendes som første argument, uten messages=: ai.chat([...]).

Be om JSON med en fast form

ai.json ber om svaret i JSON, validerer det mot et JSON Schema og returnerer JSON-en som allerede er lest:

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}
  • Skjemaet beskriver formen: typene, de obligatoriske feltene og en description for hvert felt. Jo bedre beskrivelse, jo bedre svar.
  • Et svar som ikke følger skjemaet, gir feilen invalid_output. Skriptet får aldri data med feil form.
  • Leverandører som støtter strukturert utdata, får skjemaet i forespørselen. De andre får det i systeminstruksjonen, og svaret valideres likevel.

Sende filer

files= sender filer fra appen med forespørselen, i ai.chat og i ai.json. Den tar imot argumenter av typen Upload slik de kommer i input["args"], eller det files.store returnerer:

from api_manager import ai, files


def main(input):
    # et argument av typen Upload i et API
    foto = input["args"]["foto"]
    estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])

    # en fil som skriptet selv lager
    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 Hvordan den sendes
Bilder i PNG, JPEG, GIF og WebP Som bilde, for modeller som ser bilder.
PDF Som dokument, for modeller som leser PDF.
Tekst (txt, csv, json, md, xml og yaml) Som tekst, før spørsmålet.

Hver fil kan være opptil 20 MB, og en forespørsel opptil 40 MB. En modell som bare forstår tekst, avviser bilder og PDF med feilen invalid_request.

Embeddings

ai.embed gjør tekst om til vektorer, slik at du kan søke etter mening og ikke bare etter like 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"])  # én vektor
    artigos = ["Como mudar a palavra-passe", "Prazos de entrega", "Devoluções"]
    vectores = ai.embed(artigos)  # én vektor por texto
    melhor = max(range(len(artigos)), key=lambda i: semelhanca(pergunta, vectores[i]))
    return {"artigo": artigos[melhor]}

Én tekst returnerer én vektor. En liste returnerer en liste med vektorer, i samme rekkefølge, opptil 2048 tekster per kall. Uten model= gjelder standardaliaset for embeddings.

Aliasene i appen

ai.models() returnerer aliasene i appen, hvert med navn, bruk, standardmerke, leverandør og modell. Et skript kan bruke det til å velge modell mens det kjører, eller til å forklare hvorfor et alias mangler.

Feil

Et kall som feiler, kaster ai.Error. Attributtet code er det samme for alle leverandører, og meldingen sier hva som skjedde:

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"]}
Kode Hva den betyr
not_configured Aliaset mangler, leverandøren er deaktivert, eller modellen er ikke lenger tillatt.
rate_limited Leverandøren avviste på grunn av for mange forespørsler.
timeout Leverandøren svarte ikke innen den maksimale tiden.
unavailable, connection Leverandøren er nede eller kunne ikke nås.
auth, permission Nøkkelen ble avvist eller mangler tillatelse.
invalid_request Forespørselen er ikke gyldig for denne leverandøren eller modellen.
invalid_output JSON-en i svaret følger ikke skjemaet.
refused Modellen nektet å svare.
not_supported Leverandøren gjør ikke denne operasjonen, eller filen er av en type som ikke kan sendes.
cancelled Kjøringen sluttet før svaret.
max_steps ai.run nådde det største antallet steg uten endelig svar.
not_found, unknown Modellen eller adressen finnes ikke, eller det skjedde en annen feil.

Tidsgrense og logger

  • Et svar kan ta flere titalls sekunder. Skriptets Tidsgrense må holde for alle kallene: øk den i et skript med flere kall.
  • Når kjøringen slutter, på grunn av tidsgrensen eller en avbrytelse, blir forespørslene som fortsatt venter, avbrutt hos leverandøren.
  • Hvert kall skriver en linje i loggene for kjøringen, med aliaset, modellen og varigheten, for eksempel [ai] texto (local/qwen2.5:0.5b): 1840 ms.
  • Plattformen lagrer ikke teksten i forespørslene eller svarene, med mindre appen slår på feilsøking (se Appens AI-modeller). Forespørselen går til AI-leverandøren for appen, så ikke send personopplysninger dit uten at det trengs.

Vanlige spørsmål

Kan jeg bruke AI fra en widget eller fra nettleseren? Nei. AI finnes bare i skriptene, som kjører på serveren, så nøklene kommer aldri til nettleseren. En skjerm som trenger AI, kaller et API som kjører et skript.

Skriptet sier not_configured, men aliaset finnes. Sjekk at aliaset har riktig bruk (et alias for embeddings fungerer ikke for ai.chat), at leverandøren er aktiv, og at modellen fortsatt er tillatt der.

Kan jeg bruke biblioteket fra OpenAI eller Anthropic direkte? Du kan installere det fra panelet pip, men da må nøkkelen ligge i en hemmelighet i appen, og skriptet mister aliasene og de felles feilkodene. Det er derfor modulen ai finnes.