Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Το Python SDK της xAI: Ασύγχρονες Λειτουργίες

Μάθημα 16 / 16 Ενημερώθηκε 2 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Αυτοματοποιήστε τις ροές εργασίας RAG σε Python
  2. Εγκατάσταση και Διαμόρφωση
  3. Λειτουργίες Συλλογών
  4. Προσθήκη Εγγράφου και Αναμονή για Ευρετηρίαση
  5. Αναζήτηση μέσω του SDK
  6. Μια Πλήρης Ροή Εργασίας End-to-End
  7. Βασικά σημεία
  8. Δοκιμάστε τις Γνώσεις σας

Ενημερώθηκε στις 2 Νοεμβρίου 2026. Με βάση τον κώδικα xai-sdk 1.21.0 και το επίσημο παράδειγμα της xAI: οι κλήσεις await απαιτούν τον ασύγχρονο πελάτη AsyncClient (ο Client είναι συγχρονικός), τα αντικείμενα που επιστρέφονται εκθέτουν τα πεδία collection_id, collections, matches και chunk_content, η κατάσταση ευρετηρίασης συγκρίνεται με την τιμή collections_pb2.DOCUMENT_STATUS_PROCESSED, και η μέθοδος upload_document ανεβάζει και συνδέει το αρχείο σε μία μόνο κλήση (το προηγούμενο παράδειγμα το ανέβαζε δύο φορές, χρησιμοποιώντας μια ανύπαρκτη μέθοδο). Πηγές: Collections via the API · Collections Search · xai-sdk-python.

Αυτοματοποιήστε τις ροές εργασίας RAG σε Python

Ό,τι έχετε καλέσει μέσω curl σε όλη τη διάρκεια αυτού του μαθήματος υπάρχει και σε Python: ανέβασμα εγγράφων, διαχείριση συλλογών, αναζήτηση, παραγωγή περιεχομένου. Το SDK της xAI προσφέρει δύο πελάτες, έναν συγχρονικό (Client) και έναν ασύγχρονο (AsyncClient), με πανομοιότυπες μεθόδους. Ο δεύτερος είναι η σωστή επιλογή για μια ροή εργασίας RAG, η οποία περνά το μεγαλύτερο μέρος του χρόνου της σε αναμονή—για την ολοκλήρωση μιας μεταφόρτωσης, την ευρετηρίαση ενός εγγράφου, την επιστροφή μιας αναζήτησης. Ο ασύγχρονος κώδικας διαχειρίζεται αυτές τις αναμονές παράλληλα και όχι διαδοχικά.

Εγκατάσταση και Διαμόρφωση

pip install xai-sdk

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

import os
from xai_sdk import AsyncClient

client = AsyncClient(
    api_key=os.getenv("XAI_API_KEY"),
    management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
)

Κάθε αίτημα έχει προεπιλεγμένο χρονικό όριο 27 λεπτών πριν λήξει, κάτι που καλύπτει την ανέβασμα ενός μεγάλου αρχείου PDF. Η παράμετρος timeout, σε δευτερόλεπτα, σας επιτρέπει να μειώσετε αυτό το όριο για μια διαδραστική εφαρμογή.

Λειτουργίες Συλλογών

Τρεις κλήσεις καλύπτουν τον πλήρη κύκλο ζωής. Η δημιουργία επιστρέφει το ID που θα επαναχρησιμοποιήσετε παντού αλλού:

collection = await client.collections.create(name="document-base-2026")
collection_id = collection.collection_id
print(f"Collection created: {collection_id}")

Η λίστα βοηθά κυρίως στην ανάκτηση ενός ID που δεν αποθηκεύσατε μόνιμα, ή στον έλεγχο της κατάστασης ενός λογαριασμού που κοινοποιείται σε πολλά έργα:

response = await client.collections.list()
for col in response.collections:
    print(f"{col.collection_id} — {col.collection_name} ({col.documents_count} documents)")

Η διαγραφή είναι μη αναστρέψιμη και αφαιρεί τα έγγραφα και τα ευρετήριά τους:

await client.collections.delete(collection_id)

Προσθήκη Εγγράφου και Αναμονή για Ευρετηρίαση

Μια μόνο κλήση, η upload_document, ανεβάζει το αρχείο μέσω του Files API και το συνδέει με τη συλλογή:

from pathlib import Path


async def add_document(client, collection_id, file_path):
    path = Path(file_path)
    document = await client.collections.upload_document(
        collection_id=collection_id,
        name=path.name,
        data=path.read_bytes(),
    )
    return document.file_metadata.file_id

Εάν το αρχείο υπάρχει ήδη στο Files API, η μέθοδος add_existing_document(collection_id, file_id) το συνδέει χωρίς να το ανεβάσει ξανά.

Η προσθήκη ενός εγγράφου δεν το καθιστά άμεσα διαθέσιμο για ερωτήματα. Η ευρετηρίαση απαιτεί μεταβλητό χρόνο ανάλογα με το μέγεθος του αρχείου, και μια αναζήτηση που ξεκινά πολύ νωρίς απλώς επιστρέφει λιγότερα αποτελέσματα από τα αναμενόμενα—ένα σφάλμα ιδιαίτερα οδυνηρό στη διάγνωση, καθώς δεν προκαλεί κανένα λάθος. Εξ ου και αυτός ο βρόχος αναμονής, ο οποίος ελέγχει την κατάσταση μέχρι να επιτευχθεί το DOCUMENT_STATUS_PROCESSED:

import asyncio

from xai_sdk.proto import collections_pb2


async def wait_for_indexing(client, file_id, collection_id):
    while True:
        doc = await client.collections.get_document(file_id, collection_id)
        if doc.status == collections_pb2.DOCUMENT_STATUS_PROCESSED:
            print("Document ready")
            return
        if doc.status == collections_pb2.DOCUMENT_STATUS_FAILED:
            raise RuntimeError(f"Indexing failed: {doc.error_message}")
        await asyncio.sleep(3)

Η κατάσταση είναι μια τιμή απαρίθμησης (enumeration), όχι συμβολοσειρά: η σύγκρισή της με το κείμενο "DOCUMENT_STATUS_PROCESSED" δεν θα ήταν ποτέ αληθής και ο βρόχος θα εκτελούνταν επ’ αόριστον. Για μια απλή περίπτωση, η κλήση upload_document(..., wait_for_indexing=True) διαχειρίζεται αυτή την αναμονή για εσάς.

Αναζήτηση μέσω του SDK

Η αναζήτηση επιστρέφει τα ίδια τμήματα με βαθμολογία όπως το HTTP endpoint, στη λίστα matches:

results = await client.collections.search(
    query="Order validation procedure",
    collection_ids=[collection_id],
)

for m in results.matches:
    print(f"Score: {m.score:.2f}")
    print(f"Content: {m.chunk_content[:200]}")
    print("---")

Μια Πλήρης Ροή Εργασίας End-to-End

Τα προηγούμενα μπλοκ συνδυάζονται σε ένα σενάριο που δημιουργεί τη συλλογή, ανεβάζει έγγραφα, περιμένει την ευρετηρίαση, εκτελεί αναζήτηση και στη συνέχεια παράγει μια απάντηση χρησιμοποιώντας το εργαλείο collections_search:

import asyncio
import os

from xai_sdk import AsyncClient
from xai_sdk.chat import user
from xai_sdk.tools import collections_search


async def rag_pipeline():
    client = AsyncClient(
        api_key=os.getenv("XAI_API_KEY"),
        management_api_key=os.getenv("XAI_MANAGEMENT_API_KEY"),
    )

    # 1. Δημιουργία της συλλογής
    collection = await client.collections.create(name="project-documentation")
    collection_id = collection.collection_id

    # 2. Προσθήκη εγγράφων παράλληλα
    files = [
        "docs/architecture.pdf",
        "docs/api-reference.pdf",
        "docs/deployment-guide.md",
    ]
    file_ids = await asyncio.gather(*[
        add_document(client, collection_id, f) for f in files
    ])

    # 3. Αναμονή για την ευρετηρίαση όλων των εγγράφων
    await asyncio.gather(*[
        wait_for_indexing(client, fid, collection_id) for fid in file_ids
    ])

    # 4. Αναζήτηση
    results = await client.collections.search(
        query="How to deploy to production?",
        collection_ids=[collection_id],
    )
    for m in results.matches:
        print(f"[{m.score:.2f}] {m.chunk_content[:150]}")

    # 5. Παραγωγή απάντησης με βάση τη συλλογή
    chat = client.chat.create(
        model="grok-4.7",
        tools=[collections_search(collection_ids=[collection_id])],
    )
    chat.append(user("Explain the deployment procedure and cite your sources."))
    response = await chat.sample()
    print(response.content)
    print(response.citations)


asyncio.run(rag_pipeline())

Οι δύο κλήσεις asyncio.gather() εκτελούν όλη τη δουλειά. Η πρώτη εκκινεί τις τρεις μεταφορτώσεις ταυτόχρονα αντί να περιμένει την ολοκλήρωση της καθεμίας· η δεύτερη παρακολουθεί τις τρεις εργασίες ευρετηρίασης ταυτόχρονα: ο συνολικός χρόνος πλησιάζει εκείνον του μεγαλύτερου εγγράφου, αντί του αθροίσματος όλων. Και δεδομένου ότι η αναμονή δεν μπλοκάρει τον βρόχο γεγονότων (event loop), ο ίδιος κώδικας ενσωματώνεται άμεσα σε μια εφαρμογή FastAPI ή aiohttp, η οποία συνεχίζει να εξυπηρετεί άλλα αιτήματα ενώ τα έγγραφά σας ευρετηριάζονται.

Βασικά σημεία

  • Το Python SDK της xAI υπάρχει σε συγχρονική (Client) και ασύγχρονη (AsyncClient) έκδοση· το await απαιτεί τη δεύτερη
  • Και τα δύο κλειδιά (API και Management) διαμορφώνονται στον πελάτη
  • Η upload_document ανεβάζει και συνδέει σε μία κλήση· παρακολουθήστε την ευρετηρίαση μέσω get_document ή wait_for_indexing=True
  • Το asyncio.gather() σας επιτρέπει να ανεβάζετε και να περιμένετε την ευρετηρίαση παράλληλα
  • Η παραγωγή περιεχομένου αξιοποιεί τη συλλογή με το εργαλείο collections_search, συμπεριλαμβανομένης της απάντησης και των παραπομπών

Δοκιμάστε τις Γνώσεις σας

Αρχεία, συλλογές, αναζήτηση: RAG διαχειριζόμενο από την xAI.

1. Τι σας επιτρέπει να κάνετε το Files API;

Απάντηση: Να ανεβάζετε και να διαχειρίζεστε αρχεία (λίστα, προβολή, διαγραφή) σε υποστηριζόμενες μορφές—την πρώτη ύλη για συλλογές και ερωτήματα με έγγραφα.

2. Τι είναι μια συλλογή;

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

3. Ποιοι τρόποι αναζήτησης είναι διαθέσιμοι;

Απάντηση: Λέξεις-κλειδιά (ακριβείς όροι), σημασιολογική (νόημα) και υβριδική (και τα δύο)—η επιλογή ακολουθεί τη φύση των ερωτήσεων, με την υβριδική να καλύπτει τις περισσότερες περιπτώσεις.

4. Πώς ενσωματώνεται το RAG με την παραγωγή περιεχομένου;

Απάντηση: Μέσω του εργαλείου αναζήτησης συλλογής: collections_search στο xAI SDK, file_search με IDs συλλογών στο Responses API. Το μοντέλο αναζητά στα έγγραφά σας κατά την παραγωγή και παραθέτει τις πηγές του—το πρότυπο RAG χωρίς υποδομή προς συντήρηση.

5. Ποια σημεία απαιτούν προσοχή για την παραγωγή;

Απάντηση: Εμπιστευτικότητα των ανεβασμένων δεδομένων (δικαιώματα, κύκλος ζωής), συνάφεια προς βελτιστοποίηση (μεταδεδομένα, τμηματοποίηση)—και το ασύγχρονο SDK για επεξεργασία υψηλού όγκου.

Διαχειριζόμενο RAG: εσείς φέρνετε τα έγγραφα και τις ερωτήσεις, η xAI διαχειρίζεται το ευρετήριο—διατηρήστε τον έλεγχο της εμπιστευτικότητας και της συνάφειας.