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. |
| 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.