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

Създаване на празен пакет

Урок 4 от 12 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Първа стъпка: инициализация
  2. Извикване за създаване
  3. Реализация на Python
  4. Реализация на JavaScript
  5. Ограничения на честотата на създаване
  6. Най-добри практики
  7. Ключови изводи

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

Първа стъпка: инициализация

Създаването на пакет е първото конкретно действие във Вашия работен процес. Извикването на POST /v1/batches инициализира празен контейнер, който впоследствие ще получи Вашите заявки. Тази стъпка е умишлено минималистична: тя създава идентификатора и подготвя пакета на страната на сървъра.

1

POST /v1/batches

Създава именуван пакет и връща неговия batch_id.

2

Запазете batch_id

Запазете идентификатора за последващи операции.

3

Добавете заявките

Пакетът е готов да получава заявки чрез API.

Извикване за създаване

Тялото на заявката съдържа само едно задължително поле – name:

curl -X POST https://api.x.ai/v1/batches \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "customer_review_analysis"}'

Отговорът съдържа batch_id, датите на създаване и изтичане, както и броячите на пакета, които все още са нула (пример от справочника на API):

{
  "batch_id": "batch_1934e8b5-f3dc-45f1-8329-9841b0aee9d8",
  "name": "customer_review_analysis",
  "create_time": "2025-11-11",
  "expire_time": "2025-11-12",
  "create_api_key_id": "********-****-****-****-************",
  "cancel_time": null,
  "cancel_by_xai_message": null,
  "state": {
    "num_requests": 0,
    "num_pending": 0,
    "num_success": 0,
    "num_error": 0,
    "num_cancelled": 0
  }
}

Реализация на Python

Официалният SDK се инсталира с pip install xai-sdk (версия 1.21.0 към 2 ноември 2026 г.; минимална версия Python 3.10). Той чете ключа от променливата на средата XAI_API_KEY:

from xai_sdk import Client

client = Client()

batch = client.batch.create(batch_name="customer_review_analysis")
batch_id = batch.batch_id
print(f"Batch created: {batch_id}")

Върнатият batch_id е уникалната референция за Вашия пакет. Запазете го в променлива, файл или база данни, в зависимост от Вашата архитектура.

Реализация на JavaScript

Без SDK, обикновено извикване на fetch към REST API е достатъчно:

const response = await fetch("https://api.x.ai/v1/batches", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.XAI_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ name: "customer_review_analysis" })
});

const batch = await response.json();
console.log(`Batch created: ${batch.batch_id}`);

Ограничения на честотата на създаване

Създаването на пакети е ограничено до 2 пъти в секунда на екип; самият брой пакети не е ограничен. На практика рядко ще достигнете това ограничение: обикновено създавате един пакет на операция и след това добавяте всички свои заявки към него. Ако създавате няколко в цикъл, разпределете извикванията с интервал от поне 500 милисекунди.

Най-добри практики

Именувайте пакетите си внимателно: името е задължително, затова го направете полезно. Име, което посочва набора от данни и датата (customer_reviews_2026_11_02), се открива лесно в списъка с пакети и в конзолата на xAI, която също Ви позволява да проследявате пакетите визуално.

Отбележете изтичането на срока: expire_time показва кога пакетът и неговите резултати спират да бъдат достъпни. Вашият процес на извличане трябва да се изпълни преди този момент.

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

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

  • Създаването на пакет е POST /v1/batches, чието единствено задължително поле е name
  • Отговорът съдържа уникален batch_id, който трябва да запазите за остатъка от работния процес
  • В Python официалният SDK xai-sdk предоставя client.batch.create(batch_name=...)
  • Ограничението е 2 създавания в секунда на екип, без ограничение за броя на пакетите
  • Следете expire_time и повтаряйте опита само при преходни грешки