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

Пълен сквозен конвейер

Урок 7 от 12 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Сглобяване на компонентите
  2. Пълен Python конвейер
  3. cURL конвейер стъпка по стъпка
  4. Обработка на грешки в продукционна среда
  5. Оптимизация на разходите
  6. Ключови изводи

Курсът е актуализиран на 2 ноември 2026 г. въз основа на документацията на xAI: отстъпката за пакетна обработка е 20% за допустимите текстови модели (не 50%), примерите следват REST API и официалния xai-sdk (client.batch.*; Batch API на xAI не съвпада с формата на OpenAI, следователно SDK на OpenAI не се прилага), а Responses API има предимство пред Chat Completions, който е остаряла крайна точка при xAI. Източници: Batch API · REST Reference · Batch Pricing.

Сглобяване на компонентите

Предишните уроци разгледаха всяка стъпка поотделно. Този урок ги обединява в завършен конвейер – от подготовката на данните до обработката на резултатите. В края ще разполагате със скрипт, който можете да адаптирате към вашия случай на употреба.

Пълен Python конвейер

import json
import time

from xai_sdk import Client

client = Client()  # ключът се чете от XAI_API_KEY

# --- Стъпка 1: подготовка на данните ---
documents = [
    {"id": f"doc-{i}", "text": f"Document content {i}..."}
    for i in range(100)
]

# --- Стъпка 2: запис на JSONL файла ---
with open("batch_requests.jsonl", "w", encoding="utf-8") as f:
    for doc in documents:
        ligne = {
            "custom_id": doc["id"],
            "method": "POST",
            "url": "/v1/responses",
            "body": {
                "model": "grok-4.3",
                "input": [
                    {"role": "system", "content": "Summarize in two sentences."},
                    {"role": "user", "content": doc["text"]},
                ],
                "max_output_tokens": 200,
            },
        }
        f.write(json.dumps(ligne, ensure_ascii=False) + "\n")

# --- Стъпка 3: качване на файла ---
with open("batch_requests.jsonl", "rb") as f:
    fichier = client.files.upload(f, filename="batch_requests.jsonl")

# --- Стъпка 4: създаване на пакета от файла (той вече е запечатан) ---
batch = client.batch.create(batch_name="resumes_documents", input_file_id=fichier.id)
print(f"Batch created: {batch.batch_id}")

# --- Стъпка 5: изчакване на приключване на обработката ---
while True:
    batch = client.batch.get(batch_id=batch.batch_id)
    etat = batch.state
    if batch.cancel_by_xai_message:
        raise RuntimeError(f"Batch canceled by xAI: {batch.cancel_by_xai_message}")
    if etat.num_requests > 0 and etat.num_pending == 0:
        break
    print(f"{etat.num_success + etat.num_error}/{etat.num_requests} requests processed")
    time.sleep(300)  # на всеки 5 минути

# --- Стъпка 6: извличане на резултатите, страница по страница ---
resultats, echecs = {}, []
jeton = None
while True:
    page = client.batch.list_batch_results(
        batch_id=batch.batch_id, limit=100, pagination_token=jeton
    )
    for r in page.succeeded:
        resultats[r.batch_request_id] = r.response.content
    echecs.extend(page.failed)
    if page.pagination_token is None:
        break
    jeton = page.pagination_token

with open("batch_results.json", "w", encoding="utf-8") as f:
    json.dump(resultats, f, ensure_ascii=False, indent=2)

print(f"{len(resultats)} results, {len(echecs)} failures")
print("Total cost: $%.4f" % (batch.cost_breakdown.total_cost_usd_ticks / 1e10))

Три детайла са от съществено значение. Условието за спиране изисква num_requests > 0, защото пакетът, създаден от файл, се чете във фонов режим: веднага след създаването му броячите може все още да са нули. Полето cancel_by_xai_message сигнализира за отмяна от страна на xAI, например поради невалиден ред. И накрая, цената се изразява в ticks (тикчета) – десетмилиардни части от долара.

cURL конвейер стъпка по стъпка

Ако предпочитате командния ред, ето еквивалента с cURL (използвайки jq за четене на отговорите):

# 1. Качване на JSONL файла
FILE_ID=$(curl -s -X POST https://api.x.ai/v1/files \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -F file="@batch_requests.jsonl" | jq -r '.id')
echo "File: $FILE_ID"

# 2. Създаване на пакета от файла
BATCH_ID=$(curl -s -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\": \"resumes_documents\", \"input_file_id\": \"$FILE_ID\"}" | jq -r '.batch_id')
echo "Batch: $BATCH_ID"

# 3. Четене на броячите
curl -s "https://api.x.ai/v1/batches/$BATCH_ID" \
  -H "Authorization: Bearer $XAI_API_KEY" | jq '.state'

# 4. Извличане на първата страница с резултати
curl -s "https://api.x.ai/v1/batches/$BATCH_ID/results?limit=100" \
  -H "Authorization: Bearer $XAI_API_KEY" > results-page-1.json

За получаване на следващите страници добавете &pagination_token=… със стойността, върната от предишната страница.

Обработка на грешки в продукционна среда

Един надежден конвейер прави разлика между три семейства грешки:

Грешки при подаване: качването на файла или създаването на пакета се проваля. Повторете опита при преходни грешки (изтичане на времето, ограничение на честотата, сървърна грешка) с нарастващо забавяне: 1 с, 2 с, 4 с, 8 с.

Грешки при обработка: някои заявки в рамките на пакета се провалят. Те се появяват в page.failed заедно със съобщението си; изпратете ги отново, и само тях, в нов пакет.

Изтичане на време и срок на валидност: 24-часовият прозорец е ориентировъчен, а не гарантиран. Безкомпромисно е изтичането на срока (expire_time): след този момент резултатите вече не са достъпни. Извличайте ги веднага щом пристигнат, вместо да чакате края на процеса.

# Неуспешни заявки: идентифицирайте ги за повторно изпращане в нов пакет
for r in echecs:
    print(f"Failure: {r.batch_request_id} — {r.error_message}")
a_relancer = {r.batch_request_id for r in echecs}

Оптимизация на разходите

Икономиите се натрупват чрез четири лоста. Изборът на модел е на първо място и далеч най-мощният: при стандартния тарифен план към 2 ноември 2026 г. grok-4.3 струва 1,25 щ.д. за милион входни токена и 2,50 щ.д. за изходни, срещу 2 щ.д. и 6 щ.д. за grok-4.7 (подкани под 200 000 токена). За класификация или кратко извличане по-лекият модел често е достатъчен, а отстъпката от 20% за пакетна обработка важи и за двата. Дължината на отговора е следващият фактор: max_output_tokens предотвратява плащането за ненужно дълги изходи – за класификация са достатъчни няколко токена. Подканите: премахването на десет токена от подкана, повтаряща се 50 000 пъти, спестява 500 000 входни токена. Накрая, кешът: xAI автоматично кешира идентични начала на заявките, а отстъпката за пакетна обработка важи и за токени, обслужвани от кеша; затова поставете общите инструкции в началото на всяка заявка, преди променливата част.

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

  • Един завършен конвейер обхваща шест стъпки: подготовка, JSONL, качване, създаване, мониторинг, извличане
  • Пакетът от файл се чете във фонов режим: изчакайте num_requests > 0, преди да заключите, че е приключил
  • Обработвайте трите семейства грешки: подаване, обработка, изтичане на време и срок на валидност
  • Извличайте и запазвайте резултатите веднага щом пристигнат, преди expire_time
  • Изборът на модел, дължината на изхода, кратките подкани и общите префикси максимизират икономиите