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

Добавяне на заявки в JSON

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

Обновено на 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.

Добавяне чрез API

След като пакетът бъде създаден, добавяте заявки към него чрез POST /v1/batches/{batch_id}/requests. Всеки повикване носи списък със заявки и можете да извиквате крайната точка толкова пъти, колкото е необходимо, стига пакетът да не е отменен. Този подход работи за пакети, изградени постепенно.

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

Тялото на повикването съдържа масив batch_requests. Всеки елемент сдвоява идентификатор (batch_request_id) със самата заявка, съхранена под ключа за нейния тип – responses за Responses API:

{
  "batch_requests": [
    {
      "batch_request_id": "avis-001",
      "batch_request": {
        "responses": {
          "model": "grok-4.3",
          "input": [
            {"role": "system", "content": "Classify the sentiment: positive, negative, or neutral."},
            {"role": "user", "content": "The product exceeded my expectations!"}
          ]
        }
      }
    }
  ]
}
  • batch_request_id: Вашият идентификатор, уникален в рамките на пакета. Това е ключът, който свързва заявката с нейния резултат; ако липсва, xAI генерира UUID.
  • batch_request: Заявката, под ключа за нейния тип; справочникът на API документира също chat_get_completion за формата на Chat Completions.

За изображения и видеоклипове използвайте SDK (урок 9) или JSONL файл (следващият урок).

cURL Заявка

curl -X POST "https://api.x.ai/v1/batches/$BATCH_ID/requests" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_requests": [
      {
        "batch_request_id": "article-42",
        "batch_request": {
          "responses": {
            "model": "grok-4.3",
            "input": [
              {"role": "user", "content": "Classify this text: positive, neutral, or negative."}
            ]
          }
        }
      }
    ]
  }'

Добавяне с Python SDK

При използване на SDK всяка заявка се изгражда като стандартен разговор, присвоява ѝ се batch_request_id, след което ги добавяте на порции:

from xai_sdk import Client
from xai_sdk.chat import system, user

client = Client()

documents = [
    {"id": "doc-1", "text": "First document to analyze..."},
    {"id": "doc-2", "text": "Second document to analyze..."},
    {"id": "doc-3", "text": "Third document to analyze..."},
]

batch_id = "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8"

requests = []
for doc in documents:
    chat = client.chat.create(model="grok-4.3", batch_request_id=doc["id"])
    chat.append(system("Summarize the document in two sentences."))
    chat.append(user(doc["text"]))
    requests.append(chat)

# Добавяне на порции от 100: едно API повикване на порция
for i in range(0, len(requests), 100):
    client.batch.add(batch_id=batch_id, batch_requests=requests[i:i + 100])

Документацията не задава максимален брой заявки на повикване; умерените размери на порциите просто ограничават това, което трябва да бъде изпратено отново в случай на мрежов инцидент.

Ограничения на честотата при добавяне

Екипът може да прави до 1000 повиквания за добавяне на всеки 30 секунди в плъзгащ се прозорец, споделен между всички негови пакети. Ограничението важи за повикванията, а не за заявките: с порции от 100 заявки това вече позволява повече от 3000 заявки в секунда. Две други граници са по-важни:

  • 25 MB максимум за отделна заявка, което засяга основно изображения, кодирани в base64.
  • Над 100 000 заявки в пакет, xAI може да забави обработката, за да запази стабилността на услугата.

Кога да използвате добавяне чрез API

Добавянето чрез API работи винаги, когато гъвкавостта е по-важна от предварителната подготовка. То става естественият избор, когато пакетът се изгражда постепенно: заявките, пристигащи от опашка, се добавят веднага щом се появят, докато JSONL файлът би изисквал всичко да е известно предварително – и би затворил пакета. Това е също така пътят за прототипиране, за тестване на целия работен поток с пет заявки преди мащабиране, и за хетерогенни пакети.

Валидиране на заявките

Проверете кода на състоянието на всяко повикване за добавяне: грешка на този етап означава, че порцията не е запазена и трябва да я изпратите отново. Заявката може също да се провали по-късно, по време на обработката; тогава тя се появява в резултатите със своето съобщение за грешка. Модел, който не приема пакета, се отхвърля със съобщението not supported for batch processing: проверете допустимостта на страницата на модела преди стартиране на голям пакет.

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

  • Добавянето става чрез POST /v1/batches/{id}/requests, със списък batch_requests.
  • Всяка заявка носи уникален batch_request_id и своето съдържание под ключа за нейния тип (responses, chat_get_completion).
  • SDK изгражда заявките с client.chat.create(..., batch_request_id=...) и ги добавя с client.batch.add.
  • Ограничението е 1000 повиквания за добавяне на 30 секунди за екипа, като всяко повикване може да носи много заявки.
  • За разлика от JSONL файла, добавянето чрез API оставя пакета отворен за нови допълнения.