Χρήση του GenderAPI.io V2 με Python

Προετοιμασία ενός έργου Python στον διακομιστή

Αυτός ο οδηγός καλεί το endpoint του GenderAPI.io V2 https://api.genderapi.io/api/v2/gender με το κλειδί API στην κεφαλίδα Bearer. Χρησιμοποιήστε Python 3.10 ή νεότερη έκδοση και κατεβάστε το genderapi_v2.py στο έργο σας. Το παράδειγμα χρησιμοποιεί τα urllib.request και json της τυπικής βιβλιοθήκης της Python και δεν απαιτεί κανένα πακέτο pip.

Ορίστε το GENDERAPI_API_KEY στο περιβάλλον του διακομιστή. Το YOUR_API_KEY στο παρακάτω παράδειγμα δεν είναι έγκυρο κλειδί. Μην τοποθετείτε πραγματικά διαπιστευτήρια σε αρχεία υπό έλεγχο εκδόσεων, σε κοινόχρηστα notebooks ή σε εφαρμογές που εκτελούνται στον client. Η εισαγωγή του module ή η εκτέλεσή του χωρίς επιλογές επίδειξης δεν στέλνει κανένα αίτημα.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Λήψη του genderapi_v2.py →
• Έλεγχος του κλειδιού με το δωρεάν endpoint χρήσης →

Αποστολή ρητού αιτήματος μόνο με το σύνολο δεδομένων

Αποθηκεύστε τον παρακάτω κώδικα ως single.py δίπλα στο αρχείο που κατεβάσατε και εκτελέστε python3 single.py. Το βοηθητικό module στέλνει type: name, value: Alice και options.ai_mode: off σε JSON. Η πρόβλεψη βρίσκεται στο data, ενώ οι πληροφορίες για το αίτημα και τη χρέωση βρίσκονται στο meta.

Μια επιτυχής κλήση κοστίζει 1 πίστωση, ακόμη και για άγνωστο αποτέλεσμα. Το όνομα του παραδείγματος δεν εγγυάται πρόβλεψη. Το make_item δέχεται name, email ή username και απαιτεί ρητή λειτουργία AI. Προσθέστε country μόνο όταν διαθέτετε σχετικό πλαίσιο.

Πριν στείλει οτιδήποτε, το βοηθητικό module απαιτεί ένα δεκαεξαδικό κλειδί API 24 χαρακτήρων. Αυτό ελέγχει τη μορφή του κλειδιού και όχι την ύπαρξή του. Το module απορρίπτει επίσης τις επιτυχείς αποκρίσεις της δοκιμαστικής πρόσβασης IP ως μη αναμενόμενο τρόπο πρόσβασης. Ο έλεγχος γίνεται μετά τη λήψη της απόκρισης και δεν μπορεί να ακυρώσει μια δοκιμαστική πίστωση που έχει ήδη καταναλωθεί.

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

• Όλα τα πεδία των μεμονωμένων αιτημάτων →

Αποθήκευση του αποτελέσματος μαζί με τα τεκμήρια

Μια συσχέτιση που συνάγεται δεν είναι το φύλο που δηλώνει ένα άτομο. Αποθηκεύστε χωριστά την αρχική είσοδο, τα τεκμήρια που επιστράφηκαν και ό,τι έχει δηλώσει το ίδιο το άτομο. Ένα άγνωστο αποτέλεσμα είναι έγκυρο αποτέλεσμα και δεν πρέπει να γίνει μια μαντεμένη κατηγορία στην εφαρμογή σας.

• Πεδία απόκρισης και άγνωστα αποτελέσματα →
• Ακρίβεια και βαθμός βεβαιότητας →
• Πηγές δεδομένων και χρονολογημένο προφίλ της βάσης δεδομένων →

Επεξεργασία μιας μικτής παρτίδας με διατήρηση του id κάθε γραμμής

Το GenderAPI.io V2 επεξεργάζεται μικτές παρτίδες μέσω POST https://api.genderapi.io/api/v2/gender/batch: έως 50 στοιχεία με κλειδί λογαριασμού ή έως 10 με τη δοκιμαστική πρόσβαση IP. Αυτά τα παραδείγματα απαιτούν κλειδί λογαριασμού. Δώστε σε κάθε στοιχείο ένα σταθερό και μοναδικό id και μια ρητή λειτουργία AI. Μια παρτίδα μπορεί να συνδυάζει ονόματα, διευθύνσεις email και ονόματα χρήστη, και κάθε στοιχείο μπορεί να έχει προαιρετικό πλαίσιο country.

Διαβάστε κάθε στοιχείο στο data και τη σύνοψη στο meta.summary. Μια απόκριση HTTP 200 μπορεί να περιέχει σφάλματα μεμονωμένων στοιχείων. Μια παρτίδα στην οποία απέτυχαν όλα τα στοιχεία μπορεί να επιστρέψει μια απόκριση Problem ανώτατου επιπέδου με τα αποτελέσματα. Τα επιτυχή άγνωστα αποτελέσματα μετρώνται στο succeeded. Με τα index και id συνδέετε κάθε αποτέλεσμα με τη σωστή αρχική γραμμή.

Για μεγαλύτερες εργασίες χωρίστε την είσοδο σε ομάδες των 50 στοιχείων το πολύ και στείλτε τις αρχικά μία κάθε φορά. Αποθηκεύστε κάθε απόκριση και τη σχετική χρήση πριν προχωρήσετε στην επόμενη ομάδα. Σταματήστε σε περίπτωση σφάλματος μεταφοράς, σφάλματος πρόσβασης στον λογαριασμό ή μη επιβεβαιωμένης χρέωσης και διευκρινίστε την κατάσταση της τρέχουσας ομάδας. Εισαγάγετε παράλληλες αποστολές μόνο αφού ελέγξετε τα όρια του λογαριασμού σας. Το μέγιστο μέγεθος παρτίδας δεν εγγυάται συγκεκριμένη ικανότητα επεξεργασίας.

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)

• Είσοδος, αποτελέσματα και χρέωση των παρτίδων →

Πότε να χρησιμοποιείται AI

Το forceToGenderize είναι προαιρετικό για ονόματα, διευθύνσεις email και ονόματα χρήστη. Όταν είναι ενεργό, παραλείψτε το ai_mode ή χρησιμοποιήστε fallback. Τα off και always δεν συνδυάζονται με αυτή την επιλογή και επιστρέφουν 422. Ένα θετικό αρχικό υπόλοιπο αρκεί για να ξεκινήσει ένα αίτημα, ακόμη κι αν η τελική χρέωση κάνει το υπόλοιπο αρνητικό.

Η λειτουργία ψευδωνύμων μπορεί να επιστρέψει φύλο μαζί με name: null. Μπορεί επίσης να δώσει άγνωστο αποτέλεσμα. Ούτε η κανονική εφεδρική χρήση AI ούτε η ανάλυση ψευδωνύμων εγγυώνται σωστή απάντηση ή τιμή διαφορετική από null.

Το βοηθητικό module για Python απαιτεί πάντα ai_mode. Για την ανάλυση ψευδωνύμων χρησιμοποιήστε make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Το module μετατρέπει το force_to_genderize στο πεδίο JSON forceToGenderize.

• Επιλογές AI και ανάλυση ψευδωνύμων →
• Πιστώσεις και χρήση →

Απόφαση για το τι θα κάνετε μετά από σφάλμα

Τα παραδείγματα στέλνουν κάθε λειτουργία μόνο μία φορά. Δεν την επαναλαμβάνουν ποτέ αυτόματα: μια νέα αποστολή είναι νέα λειτουργία που χρεώνεται. Μια λήξη χρονικού ορίου ή ένα σφάλμα σύνδεσης σημαίνει ότι ο client δεν έλαβε πλήρη απόκριση. Δεν αποδεικνύει ότι ο διακομιστής διέκοψε την επεξεργασία ούτε ότι δεν χρεώθηκαν πιστώσεις.

Αποθηκεύστε το request_id που επιστράφηκε και την κατάσταση της χρέωσης μαζί με την εγγραφή της εργασίας σας. Το σφάλμα που δημιουργεί το παράδειγμα διατηρεί την απόκριση για ελεγχόμενη ανάλυση, αλλά μπορεί να περιέχει την αρχική είσοδο: μη γράφετε στα συνήθη αρχεία καταγραφής ούτε ολόκληρο το σφάλμα ούτε την απόκριση ούτε το κλειδί API.

• Problem Details και αποφάσεις για νέες προσπάθειες →
• Πιστώσεις και επιβεβαίωση της χρέωσης →

Η συμπεριφορά δικτύου του παραδείγματος

Το χρονικό όριο των 10 δευτερολέπτων του urllib ισχύει για τις λειτουργίες αναμονής στα sockets. Δεν είναι εγγυημένο όριο για τη συνολική διάρκεια του αιτήματος. Το παράδειγμα απενεργοποιεί τις ανακατευθύνσεις HTTP, αναλύει τις επιτυχείς αποκρίσεις JSON και διατηρεί τις αποκρίσεις Problem του HTTP. Δεν επαναλαμβάνει ποτέ αυτόματα τα αιτήματα.

Οι τοπικοί έλεγχοι χρησιμοποιούν προσομοιωμένες αποκρίσεις μεταφοράς για επιτυχείς κλήσεις, άγνωστα αποτελέσματα, μερικώς επιτυχείς παρτίδες, πρόσβαση με λογαριασμό και σφάλματα. Επαληθεύουν τη λογική ελέγχου του παραδείγματος. Δεν μετρούν τη διαθεσιμότητα του API στην παραγωγή, την ακρίβεια του συμπερασμού ή τους χρόνους απόκρισης. Κάθε ρητή εντολή επίδειξης παρακάτω στέλνει δικό της αίτημα που χρεώνεται.

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

• Τεκμηρίωση της Python για το urllib.request →
• Τεκμηρίωση της Python για το HTTPError →

Συχνές ερωτήσεις