ONNX Runtime generate() Java API

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

• Installation und Import
• SimpleGenAI-Klasse
• Ausnahmeklasse
• Model-Klasse
• Tokenizer-Klasse
• TokenizerStream-Klasse
• Tensor-Klasse
• GeneratorParams-Klasse
• Generator-Klasse
• Sequences-Klasse
• Adapter-Klasse

Installation und Import

Die Java-API wird über das Java-Paket ai.onnxruntime.genai bereitgestellt. Die Veröffentlichung des Pakets steht noch aus. Um das Paket aus dem Quellcode zu erstellen, siehe die Anleitung zum Erstellen aus dem Quellcode.

import ai.onnxruntime.genai.*;

SimpleGenAI-Klasse

Die Klasse SimpleGenAI bietet ein einfaches Nutzungsbeispiel der GenAI-API. Sie arbeitet mit einem Modell, das Text basierend auf einem Prompt generiert und jeweils einen einzelnen Prompt verarbeitet. Nutzung

Erstellen Sie eine Instanz der Klasse mit dem Pfad zum Modell. Der Pfad muss auch die GenAI-Konfigurationsdateien enthalten.

SimpleGenAI genAI = new SimpleGenAI(folderPath);

Rufen Sie createGeneratorParams mit dem Prompt-Text auf. Legen Sie weitere Suchoptionen bei Bedarf über das GeneratorParams-Objekt mit setSearchOption fest.

GeneratorParams generatorParams = genAI.createGeneratorParams(promptText);
// .. set additional generator params before calling generate()

Rufen Sie generate mit dem GeneratorParams-Objekt und einem optionalen Listener auf.

String fullResponse = genAI.generate(generatorParams, listener);

Der Listener wird als Callback-Mechanismus verwendet, damit Token bei ihrer Generierung genutzt werden können. Erstellen Sie eine Klasse, die das Interface Consumer<String> implementiert, und übergeben Sie eine Instanz dieser Klasse als listener-Argument.

Konstruktor

public SimpleGenAI(String modelPath) throws GenAIException

Wirft

GenAIException – bei einem Fehler.

generate-Methode

Generiert Text basierend auf dem Prompt und den Einstellungen in GeneratorParams.

HINWEIS: Dies behandelt nur eine einzige Eingabesequenz (d. h. einen einzelnen Prompt, was einer Batch-Größe von 1 entspricht).

public String generate(GeneratorParams generatorParams, Consumer<String> listener) throws GenAIException

Parameter

• generatorParams: Der Prompt und die Einstellungen für die Ausführung des Modells.
• listener: Optionales Callback, um Token bereitzustellen, sobald sie generiert werden.

HINWEIS: Die Token-Generierung wird blockiert, bis die accept-Methode des Listeners zurückkehrt.

Wirft

GenAIException – bei einem Fehler.

Rückgabewerte

Der generierte Text.

Beispiel

SimpleGenAI generator = new SimpleGenAI(modelPath);
GeneratorParams params = generator.createGeneratorParams("What's 6 times 7?");
Consumer<String> listener = token -> logger.info("onTokenGenerate: " + token);
String result = generator.generate(params, listener);

logger.info("Result: " + result);

createGenerateParams-Methode

Erstellt die Generator-Parameter und fügt den Prompt-Text hinzu. Der Benutzer kann weitere Suchoptionen über das GeneratorParams-Objekt festlegen, bevor generate ausgeführt wird.

public GeneratorParams createGeneratorParams(String prompt) throws GenAIException

Parameter

• prompt: Der zu kodierende Prompt-Text.

Wirft

GenAIException – bei einem Fehler.

Rückgabewerte

Die Generator-Parameter.

Ausnahmeklasse

Eine Ausnahme, die die vom nativen Layer erzeugte Fehlermeldung und den Fehlercode enthält.

Konstruktor

public GenAIException(String message)

Beispiel

catch (GenAIException e) {
  throw new GenAIException("Token generation loop failed.", e);
}

Model-Klasse

Konstruktor

Model(String modelPath)

createTokenizer-Methode

Erstellt eine Tokenizer-Instanz für dieses Modell. Das Modell enthält die Konfigurationsinformationen, die den zu verwendenden Tokenizer bestimmen.

public Tokenizer createTokenizer() throws GenAIException

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Die Tokenizer-Instanz.

generate-Methode

public Sequences generate(GeneratorParams generatorParams) throws GenAIException

Parameter

• generatorParams: Die Generator-Parameter.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Die generierten Sequenzen.

Beispiel

Sequences output = model.generate(generatorParams);

createGeneratorParams-Methode

Erstellt eine GeneratorParams-Instanz zur Ausführung des Modells.

HINWEIS: GeneratorParams verwendet intern das Modell, daher muss die Modellinstanz gültig bleiben.

public GeneratorParams createGeneratorParams() throws GenAIException

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Die GeneratorParams-Instanz.

Beispiel

GeneratorParams params = generator.createGeneratorParams("What's 6 times 7?");

Tokenizer-Klasse

encode-Methode

Kodiert einen String in eine Sequenz von Token-IDs.

public Sequences encode(String string) throws GenAIException

Parameter

• string: Zu kodierender Text als Token-IDs.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Ein Sequences-Objekt mit einer einzelnen Sequenz darin.

Beispiel

Sequences encodedPrompt = tokenizer.encode(prompt);

decode-Methode

Dekodiert eine Sequenz von Token-IDs zu Text.

public String decode(int[] sequence) throws GenAIException

Parameter

• sequence: Sammlung von Token-IDs zur Dekodierung in Text.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Die Textdarstellung der Sequenz.

Beispiel

String result = tokenizer.decode(output_ids);

encodeBatch-Methode

Kodiert ein Array von Strings in eine Sequenz von Token-IDs für jede Eingabe.

public Sequences encodeBatch(String[] strings) throws GenAIException

Parameter

• strings: Sammlung von zu kodierenden Strings als Token-IDs.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Ein Sequences-Objekt mit einer Sequenz pro Eingabe-String.

Beispiel

Sequences encoded = tokenizer.encodeBatch(inputs);

decodeBatch-Methode

Dekodiert einen Batch von Sequenzen von Token-IDs zu Text.

public String[] decodeBatch(Sequences sequences) throws GenAIException

Parameter

• sequences: Ein Sequences-Objekt mit einer oder mehreren Sequenzen von Token-IDs.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Ein Array von Strings mit der Textdarstellung jeder Sequenz.

Beispiel

String[] decoded = tokenizer.decodeBatch(encoded);

createStream-Methode

Erstellt ein TokenizerStream-Objekt für die gestreamte Tokenisierung. Dies wird mit der Generator-Klasse verwendet, um jeden generierten Token bereitzustellen.

public TokenizerStream createStream() throws GenAIException

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Die neue TokenizerStream-Instanz.

TokenizerStream-Klasse

Diese Klasse wird verwendet, um einzelne Token bei der Verwendung von Generator.generateNextToken zu konvertieren.

Decode-Methode

public String decode(int token) throws GenAIException

Parameter

• token: Int-Wert für das Token.

Wirft

GenAIException

Tensor-Klasse

Konstruiert einen Tensor mit den angegebenen Daten, der Form und dem Elementtyp.

public Tensor(ByteBuffer data, long[] shape, ElementType elementType) throws GenAIException

Parameter

• data: Die Daten für den Tensor. Muss ein direktes ByteBuffer sein.
• shape: Die Form des Tensors.
• elementType: Der Typ der Elemente im Tensor.

Wirft

GenAIException

Beispiel

Erstellt einen 2x2 Tensor mit 32-Bit-Float-Daten.

long[] shape = {2, 2};
ByteBuffer data = ByteBuffer.allocateDirect(4 * Float.BYTES);
FloatBuffer floatBuffer = data.asFloatBuffer();
floatBuffer.put(new float[] {1.0f, 2.0f, 3.0f, 4.0f});

Tensor tensor = new Tensor(data, shape, Tensor.ElementType.float32);

GeneratorParams-Klasse

Die Klasse GeneratorParams repräsentiert die Parameter, die zur Generierung von Sequenzen mit einem Modell verwendet werden. Legen Sie den Prompt mit setInput fest und alle anderen Suchoptionen mit setSearchOption.

Erstellen eines GeneratorParams-Objekts

GeneratorParams params = new GeneratorParams(model);

setSearchOption-Methode

public void setSearchOption(String optionName, double value) throws GenAIException

Wirft

GenAIException

Beispiel

Setzt die Suchoption, um die Länge der Modellgenerierung zu begrenzen.

generatorParams.setSearchOption("max_length", 10);

setSearchOption-Methode

public void setSearchOption(String optionName, boolean value) throws GenAIException

Wirft

GenAIException

Beispiel

generatorParams.setSearchOption("early_stopping", true);

setInput-Methode

Legt den/die Prompt(s) für die Modellausführung fest. Die sequences werden durch Verwendung von Tokenizer.Encode oder EncodeBatch erstellt.

public void setInput(Sequences sequences) throws GenAIException

Parameter

• sequences: Sequenzen, die den kodierten Prompt enthalten.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Beispiel

generatorParams.setInput(encodedPrompt);

setInput-Methode

Legt die Token-IDs des/der Prompt(s) für die Modellausführung fest. Die tokenIds sind die kodierten Parameter.

public void setInput(int[] tokenIds, int sequenceLength, int batchSize)
 throws GenAIException

Parameter

• tokenIds: Die Token-IDs des/der kodierten Prompt(s).
• sequenceLength: Die Länge jeder Sequenz.
• batchSize: Größe des Batches.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

HINWEIS: Alle Sequenzen im Batch müssen die gleiche Länge haben.

Beispiel

generatorParams.setInput(tokenIds, sequenceLength, batchSize);

Generator-Klasse

Die Generator-Klasse generiert Ausgaben mit einem Modell und Generator-Parametern. Die erwartete Nutzung ist, zu loopen, bis isDone false zurückgibt. Innerhalb des Loops rufen Sie computeLogits gefolgt von generateNextToken auf.

Das neu generierte Token kann mit getLastTokenInSequence abgerufen und mit TokenizerStream.Decode dekodiert werden.

Nach Abschluss des Generierungsprozesses kann GetSequence verwendet werden, um die vollständige generierte Sequenz bei Bedarf abzurufen.

Einen Generator erstellen

Konstruiert ein Generator-Objekt mit dem angegebenen Modell und den Generator-Parametern.

Generator(Model model, GeneratorParams generatorParams)

Parameter

• model: Das Modell.
• params: Die Generator-Parameter.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

isDone-Methode

Prüft, ob der Generierungsprozess abgeschlossen ist.

public boolean isDone()

Rückgabewerte

Gibt true zurück, wenn der Generierungsprozess abgeschlossen ist, andernfalls false.

computeLogits-Methode

Berechnet die Logits für das nächste Token in der Sequenz.

public void computeLogits() throws GenAIException

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

getSequence-Methode

Ruft eine Sequenz von Token-IDs für den angegebenen Sequenzindex ab.

public int[] getSequence(long sequenceIndex) throws GenAIException

Parameter

• sequenceIndex: Der Index der Sequenz.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Ein Array von Integern mit der Sequenz von Token-IDs.

Beispiel

int[] outputIds = output.getSequence(i);

generateNextToken-Methode

Generiert das nächste Token in der Sequenz.

public void generateNextToken() throws GenAIException

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

getLastTokenInSequence-Methode

Ruft das letzte Token in der Sequenz für den angegebenen Sequenzindex ab.

public int getLastTokenInSequence(long sequenceIndex) throws GenAIException

Parameter

• sequenceIndex: Der Index der Sequenz.

Wirft

GenAIException – wenn der Aufruf der nativen GenAI-API fehlschlägt.

Rückgabewerte

Das letzte Token in der Sequenz.

Sequences-Klasse

Repräsentiert eine Sammlung von kodierten Prompts/Antworten.

numSequences-Methode

Ruft die Anzahl der Sequenzen in der Sammlung ab. Dies entspricht der Batch-Größe.

public long numSequences()

Gibt zurück

Die Anzahl der Sequenzen.

Beispiel

int numSequences = (int) sequences.numSequences();

getSequence-Methode

Ruft die Sequenz am angegebenen Index ab.

public int[] getSequence(long sequenceIndex)

Parameter

• sequenceIndex: Der Index der Sequenz.

Gibt zurück

Die Sequenz als Array von Integern.

Adapter-Klasse

Kommt sehr bald!