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

Προσθήκη εγγράφων σε μια συλλογή

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

Ενημερώθηκε στις 2 Νοεμβρίου 2026. Αυτό το μάθημα αντικατοπτρίζει την έκδοση xai-sdk 1.21.0 και την τεκμηρίωση του xAI: οι κλήσεις await απαιτούν τον ασύγχρονο AsyncClient, η κατάσταση ευρετηρίασης συγκρίνεται με τη σταθερά collections_pb2.DOCUMENT_STATUS_PROCESSED (όχι ως συμβολοσειρά) και η μαζική εισαγωγή χρησιμοποιεί τη μέθοδο upload_document, η οποία συνδυάζει και τα δύο βήματα σε μία κλήση. Πηγές: Συλλογές μέσω API · xai-sdk-python.

Γιατί η προσθήκη γίνεται σε δύο βήματα

Ίσως αναμένετε να ρίξετε απευθείας ένα αρχείο PDF σε μια συλλογή, όπως σύρετε ένα αρχείο σε έναν φάκελο. Όμως, έτσι δεν λειτουργεί το API του xAI: το έγγραφο περνά πρώτα από το Files API, το οποίο το αποθηκεύει και του εκχωρεί ένα file_id, και στη συνέχεια από το Management API, το οποίο συνδέει αυτό το αναγνωριστικό με τη συλλογή. Δύο κλήσεις, δύο κλειδιά, δύο βήματα.

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

Βήμα 1: Μεταφόρτωση του αρχείου

Τίποτα νέο εδώ· αυτό είναι το endpoint που έχετε mastered από το πρώτο μάθημα:

curl -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F "[email protected]" \
  -F "purpose=assistants"

Ανακτήστε το file_id από την απάντηση: αυτό είναι το κλειδί για το επόμενο βήμα.

Βήμα 2: Σύνδεση με τη συλλογή

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

curl -X POST https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

Μόλις γίνει δεκτή αυτή η κλήση, το xAI ξεκινά την ευρετηρίαση του περιεχομένου. Το έγγραφο περνά τότε από διάφορες καταστάσεις επεξεργασίας πριν καταστεί πραγματικά διαθέσιμο για αναζήτηση.

Περιμένετε την ολοκλήρωση της ευρετηρίασης

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

import asyncio
import os

from xai_sdk import AsyncClient
from xai_sdk.proto import collections_pb2

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


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


asyncio.run(wait_for_indexing("file_abc123", "col_xyz789"))

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

Αφαίρεση ενός εγγράφου χωρίς απώλεια δεδομένων

Η αποσύνδεση ενός αρχείου από μια συλλογή είναι μια ξεχωριστή λειτουργία από τη διαγραφή του:

curl -X DELETE \
  https://management-api.x.ai/v1/collections/col_xyz789/documents/file_abc123 \
  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"

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

Μαζικός εμπλουτισμός μιας συλλογής

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

import asyncio
import os
from pathlib import Path

from xai_sdk import AsyncClient

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

files = [
    "docs/guide-installation.pdf",
    "docs/reference-api.pdf",
    "docs/faq.md",
    "docs/changelog.txt",
]


async def populate(collection_id):
    for file_path in map(Path, files):
        # Βήματα 1 και 2 σε μία κλήση: μεταφόρτωση μέσω Files API και στη συνέχεια σύνδεση
        await client.collections.upload_document(
            collection_id=collection_id,
            name=file_path.name,
            data=file_path.read_bytes(),
        )
        print(f"Added: {file_path}")


asyncio.run(populate("col_xyz789"))

Παρατηρήστε τη μίξη μορφών στη λίστα—PDF, Markdown και απλό κείμενο συνυπάρχουν χωρίς πρόβλημα στην ίδια συλλογή, κάτι που σας γλιτώνει από την τυποποίηση των πηγών σας πριν την εισαγωγή.

Δύο κλειδιά, δύο πεδία εφαρμογής

Αυτή η διαδικασία χρησιμοποιεί δύο αναγνωριστικά πρόσβασης που δεν πρέπει να συγχέετε: το τυπικό κλειδί API (XAI_API_KEY) για τη μεταφόρτωση στο βήμα 1 και το κλειδί Management (XAI_MANAGEMENT_API_KEY) για τη σύνδεση στο βήμα 2. Το SDK λαμβάνει και τα δύο κατά τη δημιουργία του client και η μέθοδος upload_document τα χρησιμοποιεί το ένα μετά το άλλο. Επαληθεύστε ότι το δεύτερο διαθέτει την άδεια AddFileToCollection: χωρίς αυτήν, η μεταφόρτωσή σας θα succeed, η προσθήκη θα αποτύχει με σφάλμα 403 και θα accumulareτε αρχεία σωστά αποθηκευμένα αλλά απόντα από κάθε συλλογή.

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

  • Η προσθήκη σε μια συλλογή γίνεται σε δύο βήματα: μεταφόρτωση και στη συνέχεια προσθήκη
  • Ένα αρχείο μπορεί να ανήκει σε πολλαπλές συλλογές ταυτόχρονα
  • Το έγγραφο πρέπει να φτάσει στην κατάσταση DOCUMENT_STATUS_PROCESSED πριν είναι διαθέσιμο για αναζήτηση
  • Η αφαίρεση ενός εγγράφου από μια συλλογή δεν διαγράφει το υποκείμενο αρχείο
  • Απαιτούνται δύο διακριτά κλειδιά API: το τυπικό για τη μεταφόρτωση και το Management για τη συλλογή