ONNX Runtime generate() C API

Hinweis: Diese API befindet sich in der Vorschau und kann sich ändern.

Übersicht
Modell-API
Tokenizer-API
Generator-Parameter-API
Generator-API
Adapter-API
Enums und Strukturen
Hilfsfunktionen

Übersicht

Modell-API

Modell erstellen

Erstellt ein Modell aus dem angegebenen Verzeichnis. Das Verzeichnis sollte eine Datei namens genai_config.json enthalten, die der Konfigurationsspezifikation entspricht.

Parameter

Input: config_path Der Pfad zum Modellkonfigurationsverzeichnis. Der Pfad wird in UTF-8 erwartet.
Ausgabe: out Das erstellte Modell.

Rückgabewerte

OgaResult mit der Fehlermeldung, falls die Modellerstellung fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateModel(const char* config_path, OgaModel** out);

Modell zerstören

Zerstört das angegebene Modell.

Parameter

Input: model Das zu zerstörende Modell.

Rückgabewerte

void

OGA_EXPORT void OGA_API_CALL OgaDestroyModel(OgaModel* model);

Generieren

Generiert ein Array von Token-Arrays aus der Modellausführung basierend auf den angegebenen Generator-Parametern.

Parameter

Input: model Das für die Generierung zu verwendende Modell.
Input: generator_params Die für die Generierung zu verwendenden Parameter.
Ausgabe: out Die generierten Token-Sequenzen. Der Aufrufer ist verantwortlich für die Freigabe der Sequenzen mit OgaDestroySequences, nachdem er die Sequenzen nicht mehr benötigt.

Rückgabewerte

OgaResult mit der Fehlermeldung, falls die Generierung fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaGenerate(const OgaModel* model, const OgaGeneratorParams* generator_params, OgaSequences** out);

Tokenizer-API

Tokenizer erstellen

Parameter

Input: model. Das Modell, für das der Tokenizer erstellt werden soll

Rückgabewerte

OgaResult mit der Fehlermeldung, falls die Tokenizer-Erstellung fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateTokenizer(const OgaModel* model, OgaTokenizer** out);

Tokenizer zerstören

OGA_EXPORT void OGA_API_CALL OgaDestroyTokenizer(OgaTokenizer*);

Kodieren

Kodiert einen einzelnen String und fügt die kodierte Token-Sequenz zu den OgaSequences hinzu. Die OgaSequences müssen mit OgaDestroySequences freigegeben werden, wenn sie nicht mehr benötigt werden.

Parameter

Rückgabewerte

OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerEncode(const OgaTokenizer*, const char* str, OgaSequences* sequences);

Dekodieren

Dekodiert eine einzelne Token-Sequenz und gibt einen nullterminierten UTF-8-String zurück. out_string muss mit OgaDestroyString freigegeben werden.

Parameter

Rückgabewerte

OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerDecode(const OgaTokenizer*, const int32_t* tokens, size_t token_count, const char** out_string);

Batch kodieren

Parameter

OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerEncodeBatch(const OgaTokenizer*, const char** strings, size_t count, TokenSequences** out);

Batch dekodieren

OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerDecodeBatch(const OgaTokenizer*, const OgaSequences* tokens, const char*** out_strings);

Tokenizer-Strings zerstören

OGA_EXPORT void OGA_API_CALL OgaTokenizerDestroyStrings(const char** strings, size_t count);

Tokenizer-Stream erstellen

OgaTokenizerStream wird verwendet, um Token-Strings inkrementell, ein Token nach dem anderen, zu dekodieren.

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateTokenizerStream(const OgaTokenizer*, OgaTokenizerStream** out);

Tokenizer-Stream zerstören

Parameter

OGA_EXPORT void OGA_API_CALL OgaDestroyTokenizerStream(OgaTokenizerStream*);

Stream dekodieren

Dekodiert ein einzelnes Token im Stream. Wenn dies zur Generierung eines Wortes führt, wird es in 'out' zurückgegeben. Der Aufrufer ist dafür verantwortlich, jeden Teil zusammenzufügen, um das vollständige Ergebnis zu generieren. 'out' ist gültig bis zum nächsten Aufruf von OgaTokenizerStreamDecode oder wenn OgaTokenizerStream zerstört wird.

OGA_EXPORT OgaResult* OGA_API_CALL OgaTokenizerStreamDecode(OgaTokenizerStream*, int32_t token, const char** out);

Generator-Parameter-API

Generator-Parameter erstellen

Erstellt OgaGeneratorParams aus dem angegebenen Modell.

Parameter

Input: model Das für die Generierung zu verwendende Modell.
Ausgabe: out Die erstellten Generator-Parameter.

Rückgabewerte

OgaResult mit der Fehlermeldung, falls die Erstellung der Generator-Parameter fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateGeneratorParams(const OgaModel* model, OgaGeneratorParams** out);

Generator-Parameter zerstören

Zerstört die angegebenen Generator-Parameter.

Parameter

Input: generator_params Die zu zerstörenden Generator-Parameter.

Rückgabewerte

void

OGA_EXPORT void OGA_API_CALL OgaDestroyGeneratorParams(OgaGeneratorParams* generator_params);

Suchoption setzen (Nummer)

Setzt eine Suchoption, bei der die Option eine Nummer ist.

Parameter

generator_params: Das Generator-Parameter-Objekt, auf dem der Parameter gesetzt werden soll.
name: Der Name des Parameters.
value: Der zu setzende Wert.

Rückgabewerte

OgaResult mit der Fehlermeldung, falls die Erstellung der Generator-Parameter fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetSearchNumber(OgaGeneratorParams* generator_params, const char* name, double value);

Suchoption setzen (Boolesch)

Setzt eine Suchoption, bei der die Option ein Boolescher Wert ist.

Parameter

generator_params: Das Generator-Parameter-Objekt, auf dem der Parameter gesetzt werden soll.
name: Der Name des Parameters.
value: Der zu setzende Wert.

Rückgabewerte

OgaResult mit der Fehlermeldung, falls die Erstellung der Generator-Parameter fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetSearchBool(OgaGeneratorParams* generator_params, const char* name, bool value);

Graph-Erfassung mit maximaler Batch-Größe versuchen

Graph-Capture behebt die dynamischen Elemente des Berechnungsdiagramms zu konstanten Werten. Dies kann in einigen Umgebungen zu einer effizienteren Ausführung führen. Um im Graph-Capture-Modus auszuführen, muss die maximale Batch-Größe im Voraus bekannt sein. Diese Funktion kann fehlschlagen, wenn nicht genügend Speicher zum Zuweisen der angegebenen maximalen Batch-Größe vorhanden ist.

Parameter

generator_params: Das Generator-Parameter-Objekt, auf dem der Parameter gesetzt werden soll.
max_batch_size: Die maximal zuzuweisende Batch-Größe.

Rückgabewerte

OgaResult mit der Fehlermeldung, falls der Graph-Capture-Modus nicht mit der angegebenen Batch-Größe konfiguriert werden konnte.

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsTryGraphCaptureWithMaxBatchSize(OgaGeneratorParams* generator_params, int32_t max_batch_size);

Eingaben setzen

Setzt die Eingabe-IDs für die Generator-Parameter. Die Eingabe-IDs werden verwendet, um die Generierung zu starten.

Parameter

Input: generator_params Die Generator-Parameter, auf denen die Eingabe-IDs gesetzt werden sollen.
Input: input_ids Das Eingabe-ID-Array der Größe input_ids_count = batch_size * sequence_length.
Input: input_ids_count Die Gesamtzahl der Eingabe-IDs.
Input: sequence_length Die Sequenzlänge der Eingabe-IDs.
Input: batch_size Die Batch-Größe der Eingabe-IDs.

Rückgabewerte

OgaResult mit der Fehlermeldung, falls das Setzen der Eingabe-IDs fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetInputIDs(OgaGeneratorParams* generator_params, const int32_t* input_ids, size_t input_ids_count, size_t sequence_length, size_t batch_size);

Eingabesequenz setzen

Setzt die Eingabe-ID-Sequenzen für die Generator-Parameter. Die Eingabe-ID-Sequenzen werden verwendet, um die Generierung zu starten.

Parameter

Input: generator_params Die Generator-Parameter, auf denen die Eingabe-IDs gesetzt werden sollen.
Input: sequences Die Eingabe-ID-Sequenzen.

Rückgabewerte

OgaResult mit der Fehlermeldung, falls das Setzen der Eingabe-ID-Sequenzen fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetInputSequences(OgaGeneratorParams* generator_params, const OgaSequences* sequences);

Modelleingabe setzen

Setzt eine zusätzliche Modelleingabe neben den input_ids.

Parameter

generator_params: Das Generator-Parameter-Objekt, auf dem die Eingabe gesetzt werden soll.
name: Der Name des zu setzenden Parameters.
tensor: Der Wert des Parameters.

Rückgabe

OgaResult mit der Fehlermeldung, falls das Setzen der Eingabe fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaGeneratorParamsSetWhisperInputFeatures(OgaGeneratorParams*, OgaTensor* tensor);

Generator-API

Generator erstellen

Erstellt einen Generator aus dem angegebenen Modell und den Generator-Parametern.

Parameter

Input: model Das für die Generierung zu verwendende Modell.
Input: params Die für die Generierung zu verwendenden Parameter.
Ausgabe: out Der erstellte Generator.

Rückgabe

OgaResult mit der Fehlermeldung, falls die Generator-Erstellung fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateGenerator(const OgaModel* model, const OgaGeneratorParams* params, OgaGenerator** out);

Generator zerstören

Zerstört den angegebenen Generator.

Parameter

Input: generator Der zu zerstörende Generator.

Rückgabe

void

OGA_EXPORT void OGA_API_CALL OgaDestroyGenerator(OgaGenerator* generator);

Prüfen, ob die Generierung abgeschlossen ist

Gibt true zurück, wenn der Generator alle Sequenzen generiert hat.

Parameter

Input: generator Der Generator, der geprüft werden soll, ob er mit der Generierung aller Sequenzen fertig ist.

Rückgabe

True, wenn der Generator alle Sequenzen generiert hat, sonst false.

OGA_EXPORT bool OGA_API_CALL OgaGenerator_IsDone(const OgaGenerator* generator);

Eine Iteration des Modells ausführen

Berechnet die Logits aus dem Modell basierend auf den Eingabe-IDs und dem vergangenen Zustand. Die berechneten Logits werden im Generator gespeichert.

Parameter

Input: generator Der Generator, für den die Logits berechnet werden sollen.

Rückgabe

OgaResult mit der Fehlermeldung, falls die Berechnung der Logits fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaGenerator_ComputeLogits(OgaGenerator* generator);

Nächstes Token generieren

Generiert das nächste Token basierend auf den berechneten Logits unter Verwendung der konfigurierten Generierungsparameter.

Parameter

Input: generator Der Generator, für den das nächste Token generiert werden soll.

Rückgabe

OgaResult mit der Fehlermeldung, falls die Generierung des nächsten Tokens fehlschlug.

OGA_EXPORT OgaResult* OGA_API_CALL OgaGenerator_GenerateNextToken(OgaGenerator* generator);

Anzahl der Tokens abrufen

Gibt die Anzahl der Tokens in der Sequenz am angegebenen Index zurück.

Parameter

Input: generator Der Generator, von dem die Anzahl der Tokens für die Sequenz am angegebenen Index abgefragt werden soll.
Input: index. Der Index, an dem die Tokens zurückgegeben werden sollen.

Rückgabe

Die Anzahl der Tokens in der Sequenz am angegebenen Index.

OGA_EXPORT size_t OGA_API_CALL OgaGenerator_GetSequenceCount(const OgaGenerator* generator, size_t index);

Sequenz abrufen

Gibt einen Zeiger auf die Sequenzdaten am angegebenen Index zurück. Die Anzahl der Tokens in der Sequenz wird von OgaGenerator_GetSequenceCount angegeben.

Parameter

Input: generator Der Generator, von dem die Sequenzdaten für die Sequenz am angegebenen Index abgerufen werden sollen. Der Zeiger auf die Sequenzdaten am angegebenen Index. Die Sequenzdaten gehören dem OgaGenerator und werden freigegeben, wenn der OgaGenerator zerstört wird. Der Aufrufer muss die Daten kopieren, wenn sie nach der Zerstörung des OgaGenerators verwendet werden müssen.
Input: index. Der Index, an dem die Sequenz abgerufen werden soll.

Rückgabe

Ein Zeiger auf die Token-Sequenz.

OGA_EXPORT const int32_t* OGA_API_CALL OgaGenerator_GetSequenceData(const OgaGenerator* generator, size_t index);

Laufzeitoption setzen

Eine API zum Setzen von Laufzeitoptionen. Weitere Parameter werden zu dieser generischen API hinzugefügt, um Laufzeitoptionen zu unterstützen. Ein Beispiel für die Verwendung dieser API zum Beenden der aktuellen Sitzung wäre der Aufruf von SetRuntimeOption mit dem Schlüssel „terminate_session“ und dem Wert „1“: OgaGenerator_SetRuntimeOption(generator, „terminate_session“, „1“)

Weitere Details zu den aktuellen Laufzeitoptionen finden Sie hier.

Parameter

Input: generator Der Generator, auf dem die Laufzeitoption gesetzt werden soll.
Input: key Der Schlüssel zum Setzen der Laufzeitoption.
Input: value Der Wert für den angegebenen Schlüssel.

Rückgabe

void

OGA_EXPORT void OGA_API_CALL OgaGenerator_SetRuntimeOption(OgaGenerator* generator, const char* key, const char* value);

Adapter-API

Diese API wird verwendet, um feinabgestimmte Adapter, wie z. B. LoRA-Adapter, zu laden und zu wechseln.

Adapter erstellen

Erstellt das Objekt, das die Adapter verwaltet. Dieses Objekt wird verwendet, um alle Modelladapter zu laden. Es ist verantwortlich für die Referenzzählung der geladenen Adapter.

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateAdapters(const OgaModel* model, OgaAdapters** out);

Parameter

model: das OgaModel, das zuvor erstellt wurde.

Ergebnisse

out: eine Referenz auf die Liste der erstellten OgaAdapters.

Adapter laden

Lädt den Modelladapter aus dem angegebenen Adapter-Dateipfad und Adapternamen.

OGA_EXPORT OgaResult* OGA_API_CALL OgaLoadAdapter(OgaAdapters* adapters, const char* adapter_file_path, const char* adapter_name);

Parameter

adapters: Das OgaAdapters-Objekt, in das der Adapter geladen werden soll.
adapter_file_path: Der Dateipfad des zu ladenden Adapters.
adapter_name: Eine eindeutige Kennung für den zu verwendenden Adapter zur Adapterabfrage.

Rückgabewert

OgaResult mit einer Fehlermeldung, falls das Laden des Adapters fehlschlug.

Adapter entladen

Entlädt den Adapter mit der angegebenen Kennung aus der Menge der zuvor geladenen Adapter. Wenn der Adapter nicht gefunden wird oder nicht entladen werden kann (wenn er in Gebrauch ist), wird ein Fehler zurückgegeben.

OGA_EXPORT OgaResult* OGA_API_CALL OgaUnloadAdapter(OgaAdapters* adapters, const char* adapter_name);

Parameter

adapters: Das OgaAdapters-Objekt, aus dem der Adapter entladen werden soll.
adapter_name: Der Name des zu entladenden Adapters.

Rückgabewert

OgaResult mit einer Fehlermeldung, falls das Entladen des Adapters fehlschlug. Dies kann auftreten, wenn die Methode mit einem Adapter aufgerufen wird, der noch nicht geladen wurde oder von einem noch verwendeten OgaGenerator als aktiv markiert wurde.

Aktiven Adapter setzen

Setzt den Adapter mit dem angegebenen Adapternamen als aktiv für das angegebene OgaGenerator-Objekt.

OGA_EXPORT OgaResult* OGA_API_CALL OgaSetActiveAdapter(OgaGenerator* generator, OgaAdapters* adapters, const char* adapter_name);

Parameter

generator: Das OgaGenerator-Objekt, für das der aktive Adapter gesetzt werden soll.
adapters: Das OgaAdapters-Objekt, das die Modelladapter verwaltet.
adapter_name: Der Name des Adapters, der als aktiv gesetzt werden soll.

Rückgabewert

OgaResult mit einer Fehlermeldung, falls der Adapter nicht als aktiv gesetzt werden konnte. Dies kann auftreten, wenn die Methode mit einem Adapter aufgerufen wird, der zuvor nicht geladen wurde.

Enums und Strukturen

typedef enum OgaDataType {
  OgaDataType_int32,
  OgaDataType_float32,
  OgaDataType_string,  // UTF8 string
} OgaDataType;

typedef struct OgaResult OgaResult;
typedef struct OgaGeneratorParams OgaGeneratorParams;
typedef struct OgaGenerator OgaGenerator;
typedef struct OgaModel OgaModel;
typedef struct OgaBuffer OgaBuffer;

Hilfsfunktionen

GPU-Geräte-ID setzen

OGA_EXPORT OgaResult* OGA_API_CALL OgaSetCurrentGpuDeviceId(int device_id);

GPU-Geräte-ID abrufen

OGA_EXPORT OgaResult* OGA_API_CALL OgaGetCurrentGpuDeviceId(int* device_id);

Fehlermeldung abrufen

Parameter

Input: result OgaResult, das die Fehlermeldung enthält.

Rückgabe

Fehlermeldung, die in der OgaResult enthalten ist. Der const char* gehört zur OgaResult und wird freigegeben, wenn die OgaResult zerstört wird.

OGA_EXPORT const char* OGA_API_CALL OgaResultGetError(OgaResult* result);

Ergebnis zerstören

Parameter

Input: result Zu zerstörende OgaResult.

Rückgabe

void

OGA_EXPORT void OGA_API_CALL OgaDestroyResult(OgaResult*);

String zerstören

Parameter

Input: Zu zerstörender String.

Rückgabe

OGA_EXPORT void OGA_API_CALL OgaDestroyString(const char*);

Puffer zerstören

Parameter

Input: Zu zerstörender Puffer.

Rückgabe

void

OGA_EXPORT void OGA_API_CALL OgaDestroyBuffer(OgaBuffer*);

Puffertyp abrufen

Parameter

Input: der Puffer.

Rückgabe

Der Typ des Puffers.

OGA_EXPORT OgaDataType OGA_API_CALL OgaBufferGetType(const OgaBuffer*);

Anzahl der Dimensionen eines Puffers abrufen

Parameter

Input: der Puffer.

Rückgabe

Die Anzahl der Dimensionen im Puffer.

OGA_EXPORT size_t OGA_API_CALL OgaBufferGetDimCount(const OgaBuffer*);

Pufferdimensionen abrufen

Ruft die Dimensionen eines Puffers ab.

Parameter

Input: der Puffer.
Ausgabe: ein Dimensionsarray.

Rückgabe

OgaResult.

OGA_EXPORT OgaResult* OGA_API_CALL OgaBufferGetDims(const OgaBuffer*, size_t* dims, size_t dim_count);

Pufferdaten abrufen

Ruft die Daten aus einem Puffer ab.

Parameter

Rückgabe

void

OGA_EXPORT const void* OGA_API_CALL OgaBufferGetData(const OgaBuffer*);

Sequenzen erstellen

OGA_EXPORT OgaResult* OGA_API_CALL OgaCreateSequences(OgaSequences** out);

Sequenzen zerstören

Parameter

Input: sequences Zu zerstörende OgaSequences.

Rückgabe

void

Rückgabe

OGA_EXPORT void OGA_API_CALL OgaDestroySequences(OgaSequences* sequences);

Anzahl der Sequenzen abrufen

Gibt die Anzahl der Sequenzen in den OgaSequences zurück.

Parameter

Input: sequences

Rückgabe

Die Anzahl der Sequenzen in den OgaSequences.

OGA_EXPORT size_t OGA_API_CALL OgaSequencesCount(const OgaSequences* sequences);

Anzahl der Tokens in einer Sequenz abrufen

Gibt die Anzahl der Tokens in der Sequenz am angegebenen Index zurück.

Parameter

Input: sequences

Rückgabe

Die Anzahl der Tokens in der Sequenz am angegebenen Index.

OGA_EXPORT size_t OGA_API_CALL OgaSequencesGetSequenceCount(const OgaSequences* sequences, size_t sequence_index);

Sequenzdaten abrufen

Gibt einen Zeiger auf die Sequenzdaten am angegebenen Index zurück. Die Anzahl der Tokens in der Sequenz wird von OgaSequencesGetSequenceCount angegeben.

Parameter

Input: sequences

Rückgabe

Der Zeiger auf die Sequenzdaten am angegebenen Index. Der Zeiger ist gültig, bis die OgaSequences zerstört wird.

OGA_EXPORT const int32_t* OGA_API_CALL OgaSequencesGetSequenceData(const OgaSequences* sequences, size_t sequence_index);