GenderAPI.io V2:n käyttö Pythonilla

Määritä palvelinpuolen Python-projekti

Tämä opas kutsuu GenderAPI.io V2:n päätepistettä https://api.genderapi.io/api/v2/gender käyttäen API-avainta Bearer-tunnisteena. Käytä Pythonin versiota 3.10 tai uudempaa ja lataa genderapi_v2.py projektiisi. Esimerkki käyttää Pythonin standardikirjaston moduuleja urllib.request ja json; pip-pakettia ei tarvita.

Aseta GENDERAPI_API_KEY palvelimen ympäristöön. Alla olevan esimerkin YOUR_API_KEY ei ole kelvollinen avain. Pidä todelliset tunnistetiedot poissa versionhallintaan lisättävistä tiedostoista, jaettavista muistikirjoista ja asiakaspuolen sovelluksista. Moduulin tuominen tai sen suorittaminen ilman demoasetusta ei lähetä pyyntöä.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Lataa genderapi_v2.py →
• Tarkista avain maksuttomalla käyttötietojen päätepisteellä →

Lähetä yksi erikseen määritetty pyyntö, joka käyttää vain tietoaineistoa

Tallenna alla oleva koodi nimellä single.py ladatun tiedoston viereen ja suorita python3 single.py. Apumoduuli lähettää JSON-muodossa arvot type: name, value: Alice ja options.ai_mode: off. Lue arvio kentästä data sekä pyynnön ja veloituksen tiedot kentästä meta.

Onnistunut kutsu käyttää 1 krediitin myös tuntemattoman tuloksen kohdalla; esimerkkinimi ei takaa ennustetta. make_item hyväksyy arvot name, email tai username ja edellyttää erikseen määritettyä tekoälytilaa. Lisää country vain, kun sinulla on asiaankuuluva konteksti.

Ennen lähettämistä apumoduuli edellyttää 24-merkkistä heksadesimaalista API-avainta. Tämä tarkistaa muodon, ei sitä, onko avain olemassa. Moduuli hylkää myös IP-kokeilun onnistuneet vastaukset, koska käyttöoikeustila ei täsmää; tämä tarkistus tehdään vastauksen jälkeen, eikä se voi perua kokeilun veloitusta.

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

• Yksittäisen pyynnön kaikki kentät →

Säilytä tulos ja sen perusteet yhdessä

Päätelty yhteys ei ole henkilön itse ilmoittama sukupuoli. Säilytä alkuperäinen syöte, palautetut perusteet ja henkilön itse antamat tiedot erillään. Tuntematon tulos on kelvollinen tulos, eikä siitä pidä tehdä sovelluksessasi arvattua luokkaa.

• Vastauskentät ja tuntemattomat tulokset →
• Tarkkuus ja luottamusarvo selitettynä →
• Tietolähteet ja päivätty tietoaineistoprofiili →

Käsittele sekalainen eräpyyntö ja säilytä kunkin rivin id

GenderAPI.io V2 käyttää sekalaisiin eräpyyntöihin päätepistettä POST https://api.genderapi.io/api/v2/gender/batch: enintään 50 kohdetta tilin avaimella tai 10 IP-kokeilussa. Nämä esimerkit edellyttävät tilin avainta. Anna jokaiselle kohteelle pysyvä, yksilöllinen id ja erikseen määritetty tekoälytila. Eräpyyntö voi yhdistää nimiä, sähköpostiosoitteita ja käyttäjänimiä, ja jokaisella kohteella voi olla valinnainen maakonteksti.

Lue jokainen data-kentän kohde ja yhteenveto kentästä meta.summary. HTTP 200 -vastaus voi sisältää kohdekohtaisia virheitä; eräpyyntö, jonka kaikki kohteet epäonnistuivat, voi palauttaa ylätason Problem-vastauksen, joka sisältää tulokset. Onnistuneet tuntemattomat tulokset lasketaan arvoon succeeded. Alkuperäisten index- ja id-arvojen avulla voit liittää jokaisen lopputuloksen oikeaan lähderiviin.

Jaa suuremmissa töissä syötteet enintään 50 kohteen ryhmiin ja lähetä ne aluksi peräkkäin. Tallenna jokainen vastaus ja sen käyttötiedot ennen kuin jatkat. Pysähdy siirtovirheisiin, tiliin liittyviin virheisiin tai vahvistamattomaan veloitukseen ja täsmäytä nykyinen ryhmä. Lisää rinnakkaisia pyyntöjä vasta, kun olet tarkistanut tilisi rajat; suurin sallittu eräpyynnön koko ei takaa läpäisykykyä.

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

• Eräpyyntöjen syötteet, tulokset ja veloitus →

Päätä, milloin tekoälyä käytetään

forceToGenderize on valinnainen nimille, sähköpostiosoitteille ja käyttäjänimille. Kun se on käytössä, jätä ai_mode pois tai käytä arvoa fallback; off ja always ovat ristiriidassa sen kanssa ja palauttavat 422-virheen. Positiivinen alkusaldo riittää pyynnön aloittamiseen, vaikka lopullinen veloitus painaisi saldon negatiiviseksi.

Lempinimitila voi palauttaa sukupuolen, vaikka tuloksessa on name: null. Se voi myös palauttaa tuntemattoman tuloksen. Tavallinen tekoäly varalla ja lempinimipäättely eivät takaa oikeaa vastausta eivätkä muuta kuin null-arvoista vastausta.

Tämä Python-apumoduuli edellyttää aina ai_mode-arvoa. Jos haluat sallia lempinimipäättelyn, käytä kutsua make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Apumoduuli muuntaa force_to_genderize-arvon JSON-kentäksi forceToGenderize.

• Tekoälyasetukset ja lempinimipäättely →
• Krediitit ja käyttö →

Päätä, mitä teet virheen jälkeen

Esimerkit lähettävät jokaisen toiminnon kerran. Ne eivät yritä uudelleen automaattisesti: uusi lähetys on uusi veloitettava toiminto. Aikakatkaisu tai yhteysvirhe tarkoittaa, että asiakasohjelma ei saanut täydellistä vastausta; se ei todista, että palvelin lopetti käsittelyn tai että krediittejä ei veloitettu.

Tallenna palautettu pyynnön tunniste ja veloituksen tila työn tietueen yhteyteen. Virheobjekti säilyttää vastauksen hallittua tarkastelua varten, mutta se voi sisältää alkuperäisen syötteen; älä kirjoita koko objektia, vastausta tai API-avainta tavallisiin lokeihin.

• Problem Details ja uudelleenyrityksiä koskevat päätökset →
• Krediitit ja veloituksen vahvistus →

Ymmärrä, miten esimerkki käsittelee tiedonsiirron

urllibin 10 sekunnin aikakatkaisu koskee estäviä socket-toimintoja eikä ole taattu takaraja koko pyynnön kokonaiskestolle. Esimerkki poistaa HTTP-uudelleenohjaukset käytöstä, jäsentää onnistuneet JSON-vastaukset ja säilyttää Problem-tyyppiset HTTP-vastaukset. Se ei koskaan yritä uudelleen automaattisesti.

Paikalliset testit käyttävät synteettisiä siirtovastauksia onnistuneille kutsuille, tuntemattomille tuloksille, osittain onnistuneille eräpyynnöille, tilin käyttöoikeudelle ja virheille. Ne tarkistavat esimerkin ohjauslogiikan; ne eivät mittaa tuotannossa olevan API:n saatavuutta, ennusteiden tarkkuutta eikä vasteaikoja tuotannossa. Jokainen alla oleva valinnainen demokomento lähettää oman, veloitettavan pyyntönsä.

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

• Pythonin dokumentaatio: urllib.request →
• Pythonin dokumentaatio: HTTPError →

Usein kysytyt kysymykset