Batch-inferentie

De Batch API voor Large Language Models maakt asynchrone verwerking van talrijke inferentieverzoeken mogelijk en is volledig compatibel met de OpenAI API-standaard. De Batch API is een kosteneffectieve oplossing wanneer directe inferentieresultaten niet nodig zijn. Deze biedt hogere snelheidslimieten dan online aanroepen en zorgt ervoor dat resultaten binnen een redelijke termijn van 24 uur worden geleverd. Deze API is ideaal voor:

Het uitvoeren van evaluaties en data-analyse.
Het classificeren van uitgebreide datasets.
Het genereren van documentsamenvattingen in een offline modus.

Ondersteunde modellen:

Snelstart

1. Batchbestanden voorbereiden

De Batch API gebruikt bestanden in .jsonl-indeling als invoer, waarbij elke regel de details van een API-inferentieverzoek vertegenwoordigt. Beschikbare endpoints zijn /v1/chat/completions en /v1/completions.

Stel de parameter endpoint in op /v1/chat/completions of /v1/completions voor compatibiliteit met de OpenAI API.

Elk verzoek moet een unieke custom_id bevatten om inferentieresultaten na voltooiing van de batch in het uitvoerbestand te kunnen lokaliseren. Parameters in het veld body van elke regel worden als daadwerkelijke inferentieverzoekparameters naar het endpoint verzonden.

Alle verzoeken binnen één batch-JSONL-bestand moeten op hetzelfde model zijn gericht. Meng geen verzoeken voor verschillende modellen in één batch.

Hieronder staat een voorbeeldinvoerbestand met 2 verzoeken:

{"custom_id": "request-1", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "user", "content": "Hello, world!"}], "max_tokens": 400}}
{"custom_id": "request-2", "body": {"model": "deepseek/deepseek-v3-0324", "messages": [{"role": "system", "content": "You are a helpful assistant."},{"role": "user", "content": "Hello world!"}],"max_tokens": 1000}}

2. Batchinvoerbestand uploaden

Upload het batchinvoerbestand om ervoor te zorgen dat er nauwkeurig naar kan worden verwezen bij het maken van een batch. Gebruik de Files API om uw .jsonl-bestand te uploaden en stel het doel in op batch. Houd er rekening mee dat het bestand 15 dagen wordt bewaard.

Raadpleeg voor informatie over het verkrijgen van een API key API Key Management.

Codevoorbeeld Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch_input_file = client.files.create(
    file=open("batch_input.jsonl", "rb"),
    purpose="batch",
)

print(batch_input_file)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/files \
  --header 'Authorization: Bearer ${API_KEY}' \
  --form 'file=@"/your/batch_input.jsonl"' \
  --form 'purpose="batch"'

Voorbeeldrespons na een succesvolle bestandsupload:

{
    "id": "file_d2co***as73c0cjd0",
    "object": "file",
    "bytes": 238,
    "filename": "batch_input.jsonl",
    "created_at": 1754894162,
    "purpose": "batch",
    "metadata": {
        "total_requests": 2
    }
}

3. Een batch maken

Zodra het invoerbestand succesvol is geüpload, kunt u een batch starten met behulp van de ID van het geüploade File-object. Het voltooiingsvenster is vast ingesteld op 24h en kan momenteel niet worden aangepast. Codevoorbeeld Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

batch = client.batches.create(
  input_file_id="file_d2cor0es1cas73c0cj60",
  endpoint="/v1/chat/completions",
  completion_window="24h"
)
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request POST \
  --url https://api.novita.ai/openai/v1/batches \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}' \
  --data '{
      "input_file_id": "file_d2co***as73c0cjd0",
      "endpoint": "/v1/chat/completions",
      "completion_window": "24h"
  }'

Dit verzoek levert een Batch-object op dat metadata over uw batch bevat, zoals geïllustreerd in het onderstaande voorbeeld:

{
    "id": "batch_d2cq***73a68lu0",
    "object": "batch",
    "endpoint": "/v1/chat/completions",
    "input_file_id": "file_d2co***as73c0cjd0",
    "output_file_id": "",
    "error_file_id": "",
    "completion_window": "24h",
    "in_progress_at": null,
    "expires_at": null,
    "finalizing_at": null,
    "completed_at": null,
    "failed_at": null,
    "expired_at": null,
    "cancelling_at": null,
    "cancelled_at": null,
    "status": "validating",
    "errors": "",
    "version": 0,
    "created_at": "2025-08-11T16:31:52.949816948+08:00",
    "updated_at": null,
    "created_by": "8f242aa1-f725-4a67-8***9-cb68025e0976",
    "created_by_key_id": "key_cc19f96c***e7390644a37da21",
    "remark": "",
    "total": 0,
    "completed": 0,
    "failed": 0,
    "metadata": null,
    "request_counts": {
        "total": 0,
        "completed": 0,
        "failed": 0
    }
}

4. De status van een batch controleren

U kunt op elk moment de status van een batch controleren om de nieuwste batchinformatie te ontvangen. De status-enumeratiewaarden van het Batch-object zijn als volgt:

Status	Beschrijving
VALIDATING	Het invoerbestand wordt gevalideerd voordat de batch kan beginnen
PROGRESS	Batch wordt uitgevoerd
COMPLETED	Batchverwerking succesvol voltooid
FAILED	Batchverwerking mislukt
EXPIRED	Batch heeft de deadline overschreden
CANCELLING	Batch wordt geannuleerd
CANCELLED	Batch is geannuleerd

Codevoorbeeld Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)
batch = client.batches.retrieve("batch_d2cq***73a68lu0")
print(batch)

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/batches/{batch_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

5. De resultaten ophalen

Zodra de batch-inferentie is voltooid, kunt u het uitvoerbestand met resultaten downloaden met behulp van het veld output_file_id uit het Batch-object. Het uitvoerbestand met resultaten wordt 30 dagen na afloop van de batch-inferentie verwijderd, dus haal het tijdig op via de interface. Codevoorbeeld Python

from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai/v1",
    api_key="<Your API Key>",
)

content = client.files.content("example-250811-1")
print(content.read())

Curl

export API_KEY="<Your API Key>"

curl --request GET \
  --url https://api.novita.ai/openai/v1/files/{file_id}/content \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer ${API_KEY}'

De respons retourneert de ruwe bestandsinhoud. Voor batchuitvoerbestanden bevat elke regel een respons zoals deze:

{
  "custom_id": "request-2589",
  "error": null,
  "id": "batch_req_task_d2c",
  "response": {
    "body": {
      "id": "29e1432c-edfb-44a4-b531-c23c600abfae",
      "object": "chat.completion",
      "created": 1754902266,
      "model": "deepseek-test",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "Hello! 👋 How can I assist you today? 😊"
          },
          "finish_reason": "stop"
        }
      ],
      "usage": {
        "prompt_tokens": 5,
        "completion_tokens": 13,
        "total_tokens": 18
      }
    },
    "request_id": "request-2589",
    "status_code": 200
  }
}

Instructies

Beperkingen

Elke batch kan maximaal 50.000 verzoeken bevatten.
De maximale invoerbestandsgrootte per batch is 100MB.

Foutafhandeling

Fouten die tijdens batchverwerking optreden, worden vastgelegd in een afzonderlijk foutbestand, dat toegankelijk is via het veld error_file_id. Veelvoorkomende foutcodes zijn:

Foutcode	Beschrijving	Oplossing
400	Ongeldige verzoekindeling	Controleer de JSONL-syntaxis en vereiste velden
401	Authenticatie mislukt	Controleer API key
404	Batch niet gevonden	Controleer batch-ID
429	Snelheidslimiet overschreden	Verlaag de verzoekfrequentie
500	Serverfout	Neem contact met ons op

Vervallen van batches

Batches die niet binnen 24 uur zijn voltooid, gaan over naar de status EXPIRED. Niet-voltooide verzoeken worden geannuleerd, terwijl voltooide verzoeken via een uitvoerbestand worden geleverd. U betaalt alleen voor tokens die zijn verbruikt door voltooide verzoeken. De batch doet er alles aan om binnen 24 uur te voltooien.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Snelstart

1. Batchbestanden voorbereiden

2. Batchinvoerbestand uploaden

3. Een batch maken

4. De status van een batch controleren

5. De resultaten ophalen

Instructies

Beperkingen

Foutafhandeling

Vervallen van batches

Alle Batch API’s

​Snelstart

​1. Batchbestanden voorbereiden

​2. Batchinvoerbestand uploaden

​3. Een batch maken

​4. De status van een batch controleren

​5. De resultaten ophalen

​Instructies

​Beperkingen

​Foutafhandeling

​Vervallen van batches

​Alle Batch API’s

Snelstart

1. Batchbestanden voorbereiden

2. Batchinvoerbestand uploaden

3. Een batch maken

4. De status van een batch controleren

5. De resultaten ophalen

Instructies

Beperkingen

Foutafhandeling

Vervallen van batches

Alle Batch API’s