KEPLIN Docs

Työkalut ja eräajot

Anna mallin käyttää skriptin funktioita ai.run-kutsulla, ja käsittele monta pyyntöä taustalla ai.batch-kutsulla.

Kaksi toimintoa yhtä kysymystä suurempaan työhön: ai.run antaa mallin käyttää skriptin funktioita vastatessaan, ja ai.batch käsittelee monta pyyntöä taustalla.

Työkalut (ai.run)

ai.run-kutsulla malli voi pyytää skriptin funktioita vastauksen aikana: hakea tietokannasta, laskea arvon tai kutsua API:a. SDK ajaa funktion skriptissä, palauttaa tuloksen mallille ja toistaa, kunnes malli antaa lopullisen vastauksen.

from api_manager import ai, db


def stock(produto: str) -> int:
    """Unidades em armazém de um produto, pelo nome."""
    linha = db("Dados CRM").query_one("select quantidade from stock where nome = ?", [produto])
    return linha["quantidade"] if linha else 0


def preco(produto: str) -> float:
    """Preço unitário de um produto, em euros."""
    return db("Dados CRM").query_one("select preco from produtos where nome = ?", [produto])["preco"]


def main(input):
    r = ai.run(input["args"]["pergunta"], tools=[stock, preco])
    return {"resposta": r["text"], "passos": r["steps"]}
  • Työkalu on Python-funktio. Malli lukee sen nimen, docstringin ja argumenttien tyyppimerkinnät päättääkseen, milloin käyttää sitä, joten kuvaa funktio hyvin docstringissä.
  • JSON Schemaksi muuttuvat tyypit ovat str, int, float, bool, list ja dict. Argumentti, jolla on oletusarvo, on valinnainen.
  • Jos haluat määrittää argumenttien skeeman itse, anna funktion sijaan dict: {"name": "stock", "description": "...", "parameters": {...}, "function": stock}, jossa parameters on JSON Schema.
  • Tulos on sama kuin ai.chat-kutsussa, ja lisäksi steps: luettelo ajetuista työkaluista argumentteineen ja tuloksineen.
  • Työkalun poikkeus ei pysäytä tehtävää: se menee mallille tekstinä (”Erro: …”), ja malli päättää, mitä tehdä.
  • max_steps (oletuksena 10) on mallille tehtävien pyyntöjen enimmäismäärä. Jos malli pyytää työkaluja vielä sen jälkeen, ai.run nostaa poikkeuksen ai.Error koodilla max_steps.

Varoitus

Malli valitsee argumentit. Tietoja muuttava työkalu (poistaminen, sähköpostin lähettäminen, tallentaminen) ajetaan sillä, mitä malli päättää: tarkista argumentit funktion sisällä äläkä anna mallille työkaluja, joita ei voi ajaa ilman valvontaa.

ai.run ottaa samat parametrit kuin ai.chat: system, messages, model, max_tokens, temperature ja files.

Eräajot (ai.batch)

Eräajo käsittelee monta tekstipyyntöä taustalla. Palveluntarjoajalla on vastaamiseen aikaa enintään 24 tuntia. Se sopii kiireettömään työhön: viikon tukipyyntöjen tiivistämiseen, tuhansien tietueiden luokitteluun tai luettelon kääntämiseen.

Eräajo tehdään kahdessa vaiheessa. Yksi skripti lähettää pyynnöt ja tallentaa tunnisteen:

from api_manager import ai, db


def main(input):
    crm = db("Dados CRM")
    pedidos = crm.query("select id, texto from pedidos where resumo is null")
    lote = ai.batch.submit(
        [{"id": str(p["id"]), "prompt": "Resume numa frase: " + p["texto"]} for p in pedidos],
        model="texto",
    )
    crm.query("insert into lotes (id, estado) values (?, 'em curso')", [lote["id"]])
    return lote  # {"id": "lote-...", "status": "in_progress", "count": 120}

Myöhemmin toinen skripti (esimerkiksi tunneittain ajastettu) tarkistaa tilan ja lukee tulokset:

from api_manager import ai, db


def main(input):
    crm = db("Dados CRM")
    for linha in crm.query("select id from lotes where estado = 'em curso'"):
        estado = ai.batch.get(linha["id"])
        if estado["status"] == "in_progress":
            continue
        if estado["status"] == "ended":
            for r in ai.batch.results(linha["id"]):
                if r["ok"]:
                    crm.query("update pedidos set resumo = ? where id = ?", [r["text"], int(r["id"])])
        crm.query("update lotes set estado = ? where id = ?", [estado["status"], linha["id"]])
    return {"ok": True}
Funktio Mitä se tekee
ai.batch.submit(pedidos, model=None, system=None, max_tokens=None, temperature=None, schema=None) Lähettää eräajon. Kukin pyyntö on teksti tai dict, jossa on id, prompt (tai messages) ja valinnaisesti system. Palauttaa id, status ja count.
ai.batch.get(id) Tilan (in_progress, ended, failed, cancelled tai expired) ja määrät (total, succeeded, failed ja processing).
ai.batch.results(id) Valmiin eräajon tulokset: luettelo, jossa on id, ok, text, data (kun schema on annettu), error ja usage.
ai.batch.cancel(id) Peruuttaa eräajon ja palauttaa tilan.
  • Eräajossa on enintään 10 000 pyyntöä. id-arvoissa on kirjaimia, numeroita, yhdysmerkkejä ja alaviivoja, enintään 64 merkkiä, eikä niitä toisteta. Ilman id-arvoa pyynnöt numeroidaan alkaen 1:stä.
  • Kun schema on annettu, jokainen tulos validoidaan kuten ai.json-kutsussa: skeemaa vastaamattomissa tuloksissa ok on epätosi ja syy on kentässä error.
  • Eräajoja tekevät OpenAI, Anthropic ja Google Gemini API:n kautta. Muilla palveluntarjoajilla ai.batch.submit antaa virheen not_supported.
  • Eräajon tunniste toimii vain sovelluksessa, joka sen lähetti.

Usein kysyttyä

Voiko työkalu kutsua ulkoista palvelua? Voi. Työkalu on Python-funktio kuten mikä tahansa muu, ja se voi käyttää http-, db- tai workflow-moduulia.

Kauanko eräajo kestää? Se riippuu palveluntarjoajasta ja sen kuormituksesta, ja voi kestää jopa 24 tuntia. Eräajo, joka ei valmistu siinä ajassa, päättyy tilaan expired.

Voinko käyttää työkaluja eräajossa? Et. Eräajo tekee teksti- ja JSON-pyyntöjä; käytä työkaluihin ai.run-kutsua.