API: prvé volanie a kontrola nákladov

Čo vytvoríš a čo potrebuješ#

Vytvoríš malý lokálny program, ktorý pošle krátky text do API a vypíše zhrnutie. API je rozhranie pre vlastný softvér; bežné používanie Groku v chate ho nevyžaduje. Potrebuješ Python 3, internet, účet v API konzole, prístupný model a aktivované účtovanie.

Tento postup bol porovnaný s dokumentáciou. Platené volanie sme nevykonali, preto výsledok ani cenu konkrétneho behu neoznačujeme za otestované.

Priprav účet a kľúč#

V konzole vyber správny tím a skontroluj účtovanie. Začni malým rozpočtom a vypnutým automatickým dopĺňaním, kým nerozumieš spotrebe.
Na stránke API Keys vytvor kľúč len pre tento projekt. Odlož ho do správcu tajomstiev alebo do premennej prostredia.
Nastav premennú XAI_API_KEY na svoj kľúč a XAI_MODEL na identifikátor modelu uvedený nižšie. Nastavenie sa líši medzi terminálmi; v produkcii použi správu tajomstiev hostingu.
Kľúč neposielaj do prehliadača návštevníka, verejného repozitára ani promptu. Aj súbor .env musí zostať mimo verejného projektu.

Identifikátor modelu pre tento príklad:

Pred použitím over, že ho vidíš v konzole svojho tímu. Ak kľúč unikne, zruš ho, vytvor nový a prezri spotrebu.

Prvé volanie#

Ulož kód do súboru first_request.py a spusti ho príkazom python3 first_request.py v prostredí s nastavenými premennými. Používa len štandardnú knižnicu Pythonu a zdokumentované Responses API.

import json
import os
import urllib.request

payload = {
    "model": os.environ["XAI_MODEL"],
    "input": "Zhrň iba tento text jednou vetou: Stretnutie bude v utorok o 10.00. Témou je plán školenia.",
    "store": False,
}
request = urllib.request.Request(
    "https://api.x.ai/v1/responses",
    data=json.dumps(payload).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + os.environ["XAI_API_KEY"],
        "Content-Type": "application/json",
    },
    method="POST",
)
with urllib.request.urlopen(request, timeout=120) as response:
    result = json.load(response)
for item in result.get("output", []):
    for part in item.get("content", []):
        if part.get("type") == "output_text":
            print(part["text"])
print("Usage:", result.get("usage", {}))

Očakávaj jednu vetu s utorkom, časom a témou školenia. Napríklad: Ilustračný výsledok: V utorok o 10.00 sa uskutoční stretnutie o pláne školenia. Porovnaj odpoveď so vstupom a prezri údaje usage. Prázdny výstup nepovažuj za úspech: skontroluj stav a štruktúru odpovede.

store: false vypína uloženie konverzačného stavu pre pokračovanie cez Responses API. Nie je to náhrada tímového nastavenia nulového uchovávania dát (ZDR) ani sľub nulového auditného uchovávania.

Náklady pod kontrolou#

Pred dávkou najprv odošli jednu malú ukážku. Zmeraj skutočnú spotrebu na typických vstupoch, zohľadni opakovania pri chybách a až potom odhadni denný rozpočet. Limituj počet dopytov aj veľkosť podkladov vo vlastnej aplikácii. Krátka odpoveď sama osebe nezaručuje nízku spotrebu uvažovania.

Ak pridáš vyhľadávanie alebo iný nástroj, skontroluj jeho osobitnú sadzbu. Cenu obrázka, videa či hlasu neodvodzuj od sadzby textových tokenov. Použitie zahraničnej meny tu nepredstavuje oficiálnu slovenskú cenu v eurách.

Aktuálne údaje a ďalšie nástroje#

Krátky príklad vyššie pracuje len s dodaným textom. Pre aktuálnu rešerš treba v API povoliť príslušný nástroj. Dokumentácia uvádza v poli tools typ web_search pre web a x_search pre X. Samotná veta „vyhľadaj“ nenahrádza konfiguráciu nástroja vo vlastnom programe.

"tools": [{"type": "web_search"}]

Po pridaní nástroja over nielen odpoveď, ale aj vrátené odkazy a použité volania. Pri zobrazovaní výsledku zachovaj citácie. Pri funkciách, ktoré zapisujú do iných systémov, validuj argumenty na serveri a vyžiadaj konkrétne schválenie od používateľa pred nezvratným krokom.

Výstup, ktorý vie spracovať program#

Keď má odpoveď pokračovať do databázy alebo inej služby, vopred navrhni polia, dátové typy a pravidlo pre chýbajúci údaj. Napríklad číslo objednávky ako text zachová úvodné nuly; neznámy termín má byť prázdny alebo null, nie vymyslený dátum.

Pre podporovaný model použi zdokumentované štruktúrované výstupy. Na serveri potom skontroluj schému aj význam: platný JSON ešte nepotvrdzuje správny súčet, oprávneného adresáta alebo údaj zo zdroja.

Z podkladu extrahuj iba číslo objednávky, menu, sumu a termín. Chýbajúce hodnoty označ null. Neodhaduj ich. Pri každej hodnote si zachovaj odkaz na riadok alebo časť podkladu na následnú kontrolu.

Toto je návrh extrakčného zadania, nie kompletná konfigurácia API. Pred dávkou si priprav aspoň správny vstup, chýbajúce pole, zlý formát a dvojznačný údaj. Zlyhanie nesmie potichu prepísať existujúci záznam.

Keď volanie zlyhá#

401: over premennú s kľúčom a hlavičku Authorization. Kľúč nevypisuj do zdieľaného protokolu.
403: over oprávnenie tímu alebo kľúča.
404: porovnaj adresu a identifikátor modelu s dokumentáciou.
400 alebo 422: skontroluj formát JSON a podporované parametre.
429: zníž súbežnosť a počkaj. Použi obmedzený počet opakovaní s rastúcim odstupom; nekonečná slučka problém zhorší.

Pri časovom limite najprv skontroluj, či služba dopyt už nespracovala. Opakovanie môže vytvoriť ďalšiu účtovanú požiadavku. Pri širšom výpadku otvor stav služby. Do podpory posielaj identifikátor dopytu a očistený opis, nie tajný kľúč.

Dáta a ďalší krok#

Pre firemné nasadenie si zapíš účel spracovania, odosielané polia, oprávnenia, úložiská a spôsob vymazania. Nepreberaj nastavenia tréningu zo spotrebiteľského chatu ako pravidlá API. Potom priprav malú skúšobnú množinu: správny vstup, prázdny text, dlhý text a nečakaný formát. Začni automatizovať až po kontrole výsledkov a nákladov.