Премини към основното съдържание
Български— Изберете език
Меню

Формат JSONL, custom_id и качване на файлове

Урок 2 от 16 Обновен 3 ноември 2026 г. Напреднало
На тази страница
  1. Форматът JSONL: Основата на пакетното извеждане
  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: Основата на пакетното извеждане

JSONL (JSON Lines) е стандартният формат, който Mistral използва за структуриране на пакетни заявки. Всеки ред във файла представлява самостоятелен JSON обект, описващ една единствена заявка. Този дизайн е умишлен: можете да генерирате поток от файл с един милион реда, без да го зареждате изцяло в паметта, да го прочетете ред по ред и да проверите ръчно конкретни записи, когато дадена заявка се провали. За разлика от един масивен JSON масив, който Ви принуждава да заредите целия файл, само за да проверите един запис, JSONL Ви позволява да работите на ниво ред.

Структура на JSONL заявката

Всеки ред във Вашия JSONL файл трябва да съдържа две задължителни полета:

{
  "custom_id": "req-001",
  "body": {
    "max_tokens": 100,
    "messages": [
      {"role": "user", "content": "Обобщете този документ в 3 точки."}
    ]
  }
}

Полето custom_id е уникален идентификатор, който Вие дефинирате за всяка заявка. То е ключът, който прави резултатите използваеми. Mistral не гарантира реда на обработка: изходният файл може да започне със заявка номер 8 472. Без custom_id ще се окажете с куп отговори и без начин да разберете на кой документ съответства всеки от тях. Направете си навик да извличате този ID от собствената си референтна система – doc-001, email-2024-03-15-042, product-sku-ABC123 – вместо да използвате анонимен брояч. Когато даден отговор предизвика проблеми, можете да го проследите до източника, без да изпълнявате SQL заявка. Тук важат две практически правила: ID-тата трябва да са уникални в рамките на файла, в противен случай обработката ще върне грешка, и трябва да са разумно кратки, тъй като идентификатор от 200 символа прави логовете нечетими.

Полето body не изисква ново обучение: то съдържа точната структура, която бихте използвали за синхронно API обаждане към целевия крайна точка. Ако се насочвате към /v1/chat/completions, тялото е идентично с това, което бихте предали при извикване на client.chat.complete(). Подкана, валидирана интерактивно, се превръща директно в пакетна задача.

Генериране на JSONL файл с Python

Ето как програмно да генерирате JSONL файл от списък с документи:

import json

documents = [
    {"id": "doc-001", "text": "Изкуственият интелект трансформира..."},
    {"id": "doc-002", "text": "Дълбоки невронни мрежи..."},
    {"id": "doc-003", "text": "Обработка на естествен език..."},
]

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": "Вие сте асистент, който обобщава текстове."
                    },
                    {
                        "role": "user",
                        "content": f"Обобщете този текст: {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")

# Качване на JSONL файла
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"Качен файл: {batch_file.id}")
print(f"Размер: {batch_file.size_bytes} байта")
print(f"Цел: {batch_file.purpose}")

Параметърът purpose="batch" информира Mistral, че този файл е предназначен за пакетна обработка, а не за други функции като дообучение (fine-tuning) или RAG. Тази декларация за намерение диктува какво следва: файл, качен с грешна цел, ще бъде отхвърлен от задачата.

За бърз тест или за нетехнически екипи, AI Studio предлага същата услуга чрез графичния интерфейс:

  1. Отидете на console.mistral.ai/build/files
  2. Кликнете на “Upload”
  3. Изберете Вашия JSONL файл
  4. Изберете целта “Batch Processing”

Интерфейсът връща file_id, точно както API, и това е идентификаторът, който използвате за създаване на пакетната задача.

Валидиране на файла

Пакет от един милион реда, който се проваля на ред 300 поради дублиран custom_id, Ви коства пълен цикъл на изчакване. Няколко секунди локална валидация предотвратяват тази загуба. Следният скрипт извършва един проход, за да провери валидността на JSON, наличието на двете задължителни полета и уникалността на ID-тата:

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_num}: Невалиден JSON - {e}")
            continue

        # Проверка на задължителните полета
        if "custom_id" not in data:
            errors.append(f"Ред {line_num}: липсва custom_id")
        if "body" not in data:
            errors.append(f"Ред {line_num}: липсва body")

        # Проверка за уникалност на custom_id
        cid = data.get("custom_id")
        if cid in seen_ids:
            errors.append(f"Ред {line_num}: дублиран custom_id '{cid}'")
        seen_ids.add(cid)

if errors:
    print(f"Открити са {len(errors)} грешка(и):")
    for e in errors:
        print(f"  - {e}")
else:
    print(f"Файлът е валиден: {len(seen_ids)} заявки са готови.")

Направете това систематична стъпка във Вашия подготвителен процес, изпълнявана точно преди качването.

Ограничения и ограничения

Пакетирането на файлове е ограничено до един милион реда на файл, което означава, че трябва да разделите по-големи корпуси на множество подавания. Кодирането трябва да бъде UTF-8, а форматът строго изисква един JSON обект на ред: JSON обект, разпръснат на няколко реда, както се получава при misplaced json.dumps(..., indent=2), нарушава сървърното анализиране. Накрая, помнете двете вече споменати правила, тъй като нарушаването им води до провал на задачата: custom_id трябва да е уникален в рамките на файла, а body трябва да съответства на схемата на целевия крайна точка.

Ключови изводи

  • JSONL структурира Вашите пакетни заявки с един JSON обект на ред
  • Всяка заявка изисква уникален custom_id и body, съответстващ на целевия крайна точка
  • Качвайте чрез Python API (client.files.upload) или през AI Studio
  • Винаги валидирайте файла си преди подаване, за да избегнете грешки при обработката
  • Използвайте ensure_ascii=False за френски и акцентирани символи