KEPLIN Docs

Tekoälyn käyttö skripteissä

Tekstin, tietyn muotoisen JSONin ja embeddingien pyytäminen sovelluksen tekoälymalleilta, tiedostojen lähettäminen, virheiden käsittely ja tieto siitä, mitä kukin palveluntarjoaja tekee.

Sovelluksen skriptit kutsuvat tekoälyä SDK:n ai-moduulilla. Skripti valitsee mallin aliaksen nimellä, ja pyyntö lähtee alustan palvelimelta palveluntarjoajan tunnistetiedoilla. Skripti ei näe avaimia koskaan.

from api_manager import ai


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

Ennen kuin aloitat

  • Tenantilla on oltava aktiivinen tekoälypalveluntarjoaja ja sallitut mallit. Ks. Tekoälypalveluntarjoajat.
  • Sovelluksella on oltava alias jokaiselle käytölle, jota skripti pyytää. Ilman model=-parametria skripti käyttää kyseisen käytön oletusaliasta. Ks. Sovelluksen tekoälymallit.

Mitä kukin palveluntarjoaja tekee

Palveluntarjoaja Teksti, JSON ja työkalut Upotukset Kuvat Litterointi Puhe Eräajot
OpenAI Kyllä Kyllä Kyllä Kyllä Kyllä Kyllä
Anthropic Kyllä Ei Ei Ei Ei Kyllä
Microsoft Foundry Kyllä Kyllä Kyllä Kyllä Kyllä Ei
Amazon Bedrock Kyllä Titan ja Cohere Nova Canvas, Titan ja Stability Ei Ei Ei
Google Cloud Kyllä Kyllä Kyllä Kyllä Kyllä Vain Gemini API:n kautta
OpenRouter Kyllä Kyllä Kyllä Ei Ei Ei
OpenAI-yhteensopiva Kyllä Palvelimen mukaan Palvelimen mukaan Palvelimen mukaan Palvelimen mukaan Ei

Jos palveluntarjoaja ei tee toimintoa, kutsu antaa virheen not_supported. Millä tahansa palveluntarjoajalla toiminto toimii vain mallilla, joka sen tekee: tekstimalli ei luo kuvia.

Työkalut ja eräajot ovat sivulla Työkalut ja eräajot, ja kuvat, litterointi ja puhe sivulla Kuvat ja ääni.

Tekstin pyytäminen

ai.chat lähettää pyynnön ja palauttaa mallin vastauksen:

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()}
Parametri Mitä se tekee
prompt Kysymys.
system Järjestelmäohje: mallin rooli ja säännöt.
messages Keskustelu prompt-parametrin sijaan (ks. Keskustelu).
model Aliaksen nimi. Ilman sitä käytetään tekstin oletusaliasta.
max_tokens Vastauksen enimmäispituus. Ilman sitä käytetään aliaksen arvoa ja sen jälkeen alustan arvoa.
temperature 0–2. Pieni arvo antaa ennustettavampia vastauksia. Ilman sitä käytetään mallin arvoa.
files Kysymyksen mukana lähtevät tiedostot (ks. Tiedostojen lähettäminen).
stream Nimi, jotta teksti näkyy kutsujan näytöllä sitä mukaa kuin malli kirjoittaa sitä (ks. Vastaukset reaaliajassa näytöllä).

Tulos on dict:

Avain Mitä se sisältää
text Vastauksen teksti.
stop_reason Miksi malli lopetti: end, max_tokens, tool_use, refusal tai other.
usage Käytetyt tokenit kentissä input_tokens ja output_tokens.
model, provider, alias Kuka vastasi.

Jos stop_reason on max_tokens, vastaus katkesi. Nosta max_tokens-arvoa tai pyydä lyhyempää vastausta.

Keskustelu

Jatka keskustelua antamalla historia messages-parametrissa niin, että roolit user ja assistant vuorottelevat:

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

Kun mukana on sekä messages että prompt, prompt lisätään käyttäjän viimeiseksi viestiksi. Luettelon voi antaa myös ensimmäisenä argumenttina ilman messages=-nimeä: ai.chat([...]).

Tietyn muotoisen JSONin pyytäminen

ai.json pyytää vastauksen JSON-muodossa, validoi sen JSON Schemaa vasten ja palauttaa valmiiksi luetun JSONin:

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}
  • Skeema kuvaa muodon: tyypit, pakolliset kentät ja jokaisen kentän description-kuvauksen. Mitä parempi kuvaus, sitä parempi vastaus.
  • Vastaus, joka ei vastaa skeemaa, antaa virheen invalid_output. Skripti ei koskaan saa väärän muotoista dataa.
  • Palveluntarjoajat, jotka tukevat rakenteista tulostetta, saavat skeeman pyynnössä. Muut saavat sen järjestelmäohjeessa, ja vastaus validoidaan silti.

Tiedostojen lähettäminen

files= lähettää sovelluksen tiedostoja pyynnön mukana, sekä ai.chat- että ai.json-kutsussa. Se hyväksyy Upload-tyyppiset argumentit sellaisina kuin ne saapuvat input["args"]-kohtaan, tai sen, mitä files.store palauttaa:

from api_manager import ai, files


def main(input):
    # API:n Upload-tyyppinen argumentti
    foto = input["args"]["foto"]
    estado = ai.chat("Descreve o estado do equipamento nesta fotografia.", files=[foto])

    # skriptin itse luoma tiedosto
    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"]}
Tyyppi Miten se lähetetään
PNG-, JPEG-, GIF- ja WebP-kuvat Kuvana malleille, jotka näkevät kuvia.
PDF Asiakirjana malleille, jotka lukevat PDF:ää.
Teksti (txt, csv, json, md, xml ja yaml) Tekstinä ennen kysymystä.

Kukin tiedosto voi olla enintään 20 Mt ja pyyntö enintään 40 Mt. Pelkkää tekstiä ymmärtävä malli hylkää kuvat ja PDF:t virheellä invalid_request.

Embeddingit

ai.embed muuttaa tekstin vektoreiksi, jotta voit hakea merkityksen eikä vain samojen sanojen perusteella:

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

Yksi teksti palauttaa yhden vektorin. Lista palauttaa listan vektoreita samassa järjestyksessä, enintään 2048 tekstiä kutsua kohden. Ilman model=-parametria käytetään embeddingien oletusaliasta.

Sovelluksen aliakset

ai.models() palauttaa sovelluksen aliakset, kunkin nimen, käytön, oletusmerkinnän, palveluntarjoajan ja mallin. Skripti voi käyttää sitä mallin valintaan suorituksen aikana tai kertoakseen, miksi alias puuttuu.

Virheet

Epäonnistunut kutsu nostaa poikkeuksen ai.Error. Attribuutti code on sama kaikilla palveluntarjoajilla, ja viesti kertoo, mitä tapahtui:

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"]}
Koodi Mitä se tarkoittaa
not_configured Alias puuttuu, palveluntarjoaja on pois käytöstä tai malli ei ole enää sallittu.
rate_limited Palveluntarjoaja hylkäsi liian monen pyynnön vuoksi.
timeout Palveluntarjoaja ei vastannut enimmäisajassa.
unavailable, connection Palveluntarjoaja ei ole käytettävissä tai siihen ei saatu yhteyttä.
auth, permission Avain hylättiin tai sillä ei ole oikeutta.
invalid_request Pyyntö ei kelpaa tälle palveluntarjoajalle tai mallille.
invalid_output Vastauksen JSON ei vastaa skeemaa.
refused Malli kieltäytyi vastaamasta.
not_supported Palveluntarjoaja ei tee tätä toimintoa, tai tiedosto on tyyppiä, jota ei lähetetä.
cancelled Suoritus päättyi ennen vastausta.
max_steps ai.run saavutti vaiheiden enimmäismäärän ilman lopullista vastausta.
not_found, unknown Mallia tai osoitetta ei ole, tai tapahtui jokin muu virhe.

Aikaraja ja lokit

  • Vastaus voi kestää kymmeniä sekunteja. Skriptin Aikaraja-asetuksen on riitettävä kaikille kutsuille: nosta sitä skriptissä, joka tekee useita kutsuja.
  • Kun suoritus päättyy aikarajaan tai peruutukseen, vielä odottavat pyynnöt perutaan palveluntarjoajalla.
  • Jokainen kutsu kirjoittaa suorituksen lokeihin rivin, jossa on alias, malli ja kesto, esimerkiksi [ai] texto (local/qwen2.5:0.5b): 1840 ms.
  • Alusta ei tallenna pyyntöjen eikä vastausten tekstiä, ellei sovellus ota virheenjäljitystä käyttöön (ks. Sovelluksen tekoälymallit). Pyyntö menee sovelluksen tekoälypalveluntarjoajalle, joten älä lähetä sille henkilötietoja tarpeettomasti.

Usein kysyttyä

Voinko käyttää tekoälyä widgetistä tai selaimesta? Et voi. Tekoäly on käytettävissä vain skripteissä, jotka ajetaan palvelimella, joten avaimet eivät koskaan päädy selaimeen. Tekoälyä tarvitseva näyttö kutsuu API:a, joka ajaa skriptin.

Skripti sanoo not_configured, vaikka alias on olemassa. Tarkista, että aliaksen käyttö on oikea (embeddings-alias ei käy ai.chat-kutsuun), että palveluntarjoaja on aktiivinen ja että malli on yhä sallittu siinä.

Voinko käyttää OpenAI:n tai Anthropicin kirjastoa suoraan? Voit asentaa sen pip-paneelista, mutta avaimen pitäisi silloin olla sovelluksen salaisuudessa, ja skripti menettäisi aliakset ja yhteiset virhekoodit. ai-moduuli on olemassa juuri tätä varten.