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

Μορφή JSONL, custom_id και Μεταφόρτωση Αρχείου

Μάθημα 2 / 16 Ενημερώθηκε 3 Νοεμβρίου 2026 Προχωρημένος
Σε αυτήν τη σελίδα
  1. Η Μορφή JSONL: Ο Σκελετός της Συλλογικής Εξαγωγής (Batch Inference)
  2. Δομή Αιτήματος JSONL
  3. Δημιουργία Αρχείου JSONL σε Python
  4. Μεταφόρτωση του Αρχείου στη Mistral
  5. Επικύρωση Αρχείου
  6. Όρια και Περιορισμοί
  7. Βασικά σημεία

Ενημερώθηκε στις 3 Νοεμβρίου 2026: Με το SDK mistralai 3.7.0, η files.upload αναμένει file={"file_name": …, "content": …} (η μετάδοση πλειάδας προκαλεί ValidationError πριν σταλεί οποιοδήποτε δεδομένο), και το μέγεθος του αρχείου είναι διαθέσιμο στο size_bytes.

Η Μορφή JSONL: Ο Σκελετός της Συλλογικής Εξαγωγής (Batch Inference)

Το JSONL (JSON Lines) είναι η τυπική μορφή που χρησιμοποιεί η Mistral για τη δομή των αιτημάτων συλλογικής επεξεργασίας. Κάθε γραμμή στο αρχείο αποτελεί ένα αυτόνομο αντικείμενο JSON που αντιπροσωπεύει ένα μοναδικό αίτημα. Αυτός ο σχεδιασμός είναι σκόπιμος: μπορείτε να δημιουργήσετε ροή (stream) για ένα αρχείο ενός εκατομμυρίου γραμμών χωρίς να το φορτώσετε ολόκληρο στη μνήμη, να το διαβάσετε γραμμή-γραμμή και να επιθεωρήσετε συγκεκριμένες καταχωρήσεις χειροκίνητα όταν αποτύχει ένα αίτημα. Σε αντίθεση με έναν τεράστιο πίνακα JSON, ο οποίος σας αναγκάζει να φορτώσετε ολόκληρο το αρχείο απλώς για να επαληθεύσετε μία καταχώρηση, το JSONL σας επιτρέπει να εργάζεστε σε επίπεδο γραμμής.

Δομή Αιτήματος JSONL

Κάθε γραμμή στο αρχείο JSONL πρέπει να περιέχει δύο υποχρεωτικά πεδία:

{
  "custom_id": "req-001",
  "body": {
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Summarize this document in 3 points."}
    ]
  }
}

Το custom_id είναι ένα μοναδικό αναγνωριστικό που ορίζετε εσείς για κάθε αίτημα. Αυτό είναι που καθιστά τα αποτελέσματα χρήσιμα. Η Mistral δεν εγγυάται τη σειρά επεξεργασίας: το αρχείο εξόδου μπορεί να ξεκινά με το αίτημα 8.472. Χωρίς custom_id, καταλήγετε με έναν σωρό απαντήσεων και κανέναν τρόπο να γνωρίζετε σε ποιο έγγραφο αντιστοιχεί η καθεμία. Κάντε συνήθεια να παράγετε αυτό το ID από το δικό σας σύστημα αναφοράς—doc-001, email-2024-03-15-042, product-sku-ABC123—αντί να χρησιμοποιείτε έναν ανώνυμο μετρητή. Όταν μια απάντηση προκαλεί προβλήματα, μπορείτε να την εντοπίσετε στην πηγή χωρίς να εκτελέσετε ερώτημα SQL. Εδώ ισχύουν δύο πρακτικοί κανόνες: τα IDs πρέπει να είναι μοναδικά εντός του αρχείου, διαφορετικά η επεξεργασία θα επιστρέψει σφάλμα, και πρέπει να είναι λογικά σύντομα, καθώς ένα αναγνωριστικό 200 χαρακτήρων καθιστά τα αρχεία καταγραφής (logs) δυσανάγνωστα.

Το πεδίο body δεν απαιτεί νέα μάθηση: περιέχει την ακριβή δομή που θα χρησιμοποιούσατε για μια σύγχρονη κλήση API στο endpoint προορισμού. Αν στοχεύετε στο /v1/chat/completions, το body είναι πανομοιότυπο με αυτό που θα περνούσατε σε μια κλήση client.chat.complete(). Ένα prompt που επικυρώθηκε διαδραστικά μεταφράζεται άμεσα σε μια εργασία συλλογικής επεξεργασίας.

Δημιουργία Αρχείου JSONL σε Python

Ορίστε πώς να δημιουργήσετε προγραμματιστικά ένα αρχείο JSONL από μια λίστα εγγράφων:

import json

documents = [
    {"id": "doc-001", "text": "Artificial intelligence is transforming..."},
    {"id": "doc-002", "text": "Deep neural networks..."},
    {"id": "doc-003", "text": "Natural language processing..."},
]

with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
    for doc in documents:
        request = {
            "custom_id": doc["id"],
            "body": {
                "model": "mistral-small-latest",
                "max_tokens": 200,
                "messages": [
                    {
                        "role": "system",
                        "content": "You are an assistant that summarizes texts."
                    },
                    {
                        "role": "user",
                        "content": f"Summarize this text: {doc['text']}"
                    }
                ]
            }
        }
        f.write(json.dumps(request, ensure_ascii=False) + "\n")

Σημειώστε την παράμετρο ensure_ascii=False. Χωρίς αυτήν, η json.dumps διαφεύγει τους τονισμένους χαρακτήρες ως ακολουθίες \uXXXX. Το αρχείο παραμένει έγκυρο, αλλά γίνεται αδύνατο να διαβαστεί από ανθρώπους, μετατρέποντας οποιαδήποτε αποσφαλμάτωση σε γαλλικό σώμα κειμένου σε άσκηση αποκρυπτογράφησης. Κάντε το αυτό προεπιλογή σας από την πρώτη γραμμή κώδικα.

Μεταφόρτωση του Αρχείου στη Mistral

Σε περιβάλλον παραγωγής, η μεταφόρτωση γίνεται μέσω του Python API:

from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Upload the JSONL file
with open("batch_requests.jsonl", "rb") as f:
    batch_file = client.files.upload(
        file={"file_name": "batch_requests.jsonl", "content": f},
        purpose="batch"
    )

print(f"Uploaded file: {batch_file.id}")
print(f"Size: {batch_file.size_bytes} bytes")
print(f"Purpose: {batch_file.purpose}")

Η παράμετρος purpose="batch" ενημερώνει τη Mistral ότι αυτό το αρχείο προορίζεται για συλλογική επεξεργασία και όχι για άλλες λειτουργίες όπως η βελτιστοποίηση (fine-tuning) ή το RAG. Αυτή η δήλωση πρόθεσης υπαγορεύει τι συμβαίνει στη συνέχεια: ένα αρχείο που μεταφορτώνεται με λάθος πρόθεση θα απορριφθεί από την εργασία.

Για ένα γρήγορο τεστ ή για μη τεχνικές ομάδες, το AI Studio προσφέρει την ίδια υπηρεσία μέσω του γραφικού περιβάλλοντος (GUI):

  1. Μεταβείτε στο console.mistral.ai/build/files
  2. Κάντε κλικ στο “Upload”
  3. Επιλέξτε το αρχείο JSONL σας
  4. Επιλέξτε την πρόθεση “Batch Processing”

Η διεπαφή επιστρέφει ένα file_id, ακριβώς όπως το API, και αυτό είναι το αναγνωριστικό που χρησιμοποιείτε για να δημιουργήσετε την εργασία συλλογικής επεξεργασίας.

Επικύρωση Αρχείου

Μια συλλογική επεξεργασία ενός εκατομμυρίου γραμμών που αποτυγχάνει στη γραμμή 300 λόγω διπλότυπου custom_id σας κοστίζει έναν πλήρη κύκλο αναμονής. Λίγα δευτερόλεπτα τοπικής επικύρωσης αποτρέπουν αυτή την απώλεια. Το παρακάτω σενάριο εκτελεί έναν ενιαίο έλεγχο για την εγκυρότητα JSON, την παρουσία των δύο υποχρεωτικών πεδίων και τη μοναδικότητα των IDs:

import json

errors = []
seen_ids = set()

with open("batch_requests.jsonl", "r", encoding="utf-8") as f:
    for line_num, line in enumerate(f, 1):
        try:
            data = json.loads(line)
        except json.JSONDecodeError as e:
            errors.append(f"Line {line_num}: Invalid JSON - {e}")
            continue

        # Check required fields
        if "custom_id" not in data:
            errors.append(f"Line {line_num}: missing custom_id")
        if "body" not in data:
            errors.append(f"Line {line_num}: missing body")

        # Check custom_id uniqueness
        cid = data.get("custom_id")
        if cid in seen_ids:
            errors.append(f"Line {line_num}: duplicate custom_id '{cid}'")
        seen_ids.add(cid)

if errors:
    print(f"{len(errors)} error(s) found:")
    for e in errors:
        print(f"  - {e}")
else:
    print(f"File valid: {len(seen_ids)} requests ready.")

Κάντε αυτό ένα συστηματικό βήμα στον αγωγό προετοιμασίας σας, εκτελούμενο ακριβώς πριν τη μεταφόρτωση.

Όρια και Περιορισμοί

Η ομαδοποίηση αρχείων περιορίζεται σε ένα εκατομμύριο γραμμές ανά αρχείο, πράγμα που σημαίνει ότι πρέπει να διαιρέσετε μεγαλύτερα σώματα κειμένου σε πολλαπλές υποβολές. Η κωδικοποίηση πρέπει να είναι UTF-8 και η μορφή απαιτεί αυστηρά ένα αντικείμενο JSON ανά γραμμή: ένα αντικείμενο JSON απλωμένο σε πολλές γραμμές, όπως παράγεται από μια misplaced json.dumps(..., indent=2), διακόπτει την ανάλυση στην πλευρά του διακομιστή. Τέλος, θυμηθείτε τους δύο κανόνες που αναφέρθηκαν ήδη, καθώς η παραβίασή τους προκαλεί αποτυχία της εργασίας: το custom_id πρέπει να είναι μοναδικό εντός του αρχείου και το body πρέπει να ταιριάζει με το σχήμα του endpoint προορισμού.

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

  • Το JSONL δομεί τα αιτήματα συλλογικής επεξεργασίας σας με ένα αντικείμενο JSON ανά γραμμή
  • Κάθε αίτημα απαιτεί ένα μοναδικό custom_id και ένα body που ταιριάζει με το endpoint προορισμού
  • Μεταφορτώστε μέσω του Python API (client.files.upload) ή μέσω του AI Studio
  • Επικυρώνετε πάντα το αρχείο σας πριν την υποβολή για να αποφύγετε σφάλματα επεξεργασίας
  • Χρησιμοποιήστε ensure_ascii=False για γαλλικούς και τονισμένους χαρακτήρες