Sure, you can handle it. But should you?
Let our experts manage the tech maintenance while you focus on your business.
Let our experts manage the tech maintenance while you focus on your business.
Schnittstellenbeschreibung
api.chat.v1beta.generate
Einleitung
Dieses Dokument beschäftigt sich mit der Mindbreeze Web API zum Generieren von Chat- Completions mittels RAG Pipelines.
Generate-Anfragen werden als HTTP POST-Request an ein Client Service gesendet. Der Pfad für Generate-Anfragen lautet:
<Client Service>/api/chat/v1beta/generate
Im Body des HTTP-Request wird ein JSON-Dokument mitgeschickt, das die Generate-Anfrage beschreibt. Wie dieses JSON-Dokument auszusehen hat, wird im Kapitel "Felder Im Request" beschrieben.
Als Response erhält man ebenfalls Server Sent Events (Stream). Das Format wird im Kapitel "Felder in der Response" beschrieben.
Eine OpenAPI Spezifikation der API ist ebenfalls verfügbar. Eine genauere Anleitung dazu befindet sich in der Dokumentation OpenAPI Schnittstellenbeschreibung .
Felder im Request [ConversationInput]
id (optional) | Kennung der Konversation (optional). Die ID wird in der app.telemetry angezeigt. Type: String |
inputs | Eingabetext für die Generate-Anfrage. Type: String |
stream | Steuert, ob die Generierung gestreamed wird. Standardwert: true Type: Boolean |
model_id | ID der zu verwendenden RAG Pipeline. Type: String |
pipeline_id | Alias zu model_id. Type: String |
pipeline_key | Der Schlüssel einer Pipeline. Für mehr Informationen, siehe hier. Type: String |
messages | Konversationsverlauf (optional). Siehe das Kapitel messages [liste]. |
parameters | Generierungsparameter (optional). Siehe das Kapitel parameters. |
prompt_dictionary | Zusätzliche Werte der Promptvorlage (optional). Siehe das Kapitel prompt_dictionary. |
retrieval_options | Zusätzliche Einschränkungen der Suche (optional). Siehe das Kapitel retrieval_options. |
generation_options | Zusätzliche Einstellmöglichkeiten für die Generierung (optional). Für mehr Informationen, siehe das Kapitel generation_options. |
{
"inputs": "Who is the CEO of Mindbreeze?",
"model_id": "3a0e8612-a24f-4b16-93cc-aa6307d0c62b",
"retrieval_options": {
"constraint": {
"unparsed": "title:management"
}
}
}
messages [Liste]
Die API ist stateless. Um den Generate Endpoint für Chat- Anwendungen zu verwenden, kann optional eine Chat- Verlauf als Liste von Messages angegeben werden. Dazu muss auch die Option „Chat History verwenden“ in der Pipeline aktiviert sein.
from | Absender der Message („user“ oder „assistant“). Type: String |
id | Kennung der Message (optional). Type: String |
content | Textinhalt der Message. Type: String |
content_processed | Ausgefüllte Promptvorlage mit Suchergebnissen (optional). Type: String |
[
{
"from": "user",
"content": "Who is the CEO of Mindbreeze?",
"content_processed": "Given the following extracted parts of …"
},
{
"from": assistant",
"content": "Daniel Fallmann is the CEO of Mindbreeze"
}
]
parameters
Optional können die Generation-Parameter der verwendeten Pipeline überschrieben werden.
temperature | Überschreibt „Zufälligkeit der Antwort (Temperatur)“ Steuert die Zufälligkeit der generierten Antwort (0 - 100%). Höhere Werte machen die Ausgabe kreativer, während niedrigere Werte sie zielgerichteter und deterministischer machen. Type: Integer |
max_new_tokens | Überschreibt „Maximale Länge der Antwort (Tokens)“ Begrenzt die Menge der erzeugten Tokens (100 Token ~ 75 Wörter; abhängig vom Tokenizer). Type: Integer |
details | Fügt der Antwort zusätzlich zum generierten Text noch detailliertere Informationen über die einzelnen Tokens hinzu. Type: Boolean Hinweis: Ist nur relevant, wenn es nicht gestreamed wird. |
retrieval_details | Fügt der Antwort zusätzlich noch detaillierte Informationen über die erhaltenen Antworten aus dem Retrieval Prozess hinzu. Type: Boolean |
{
"temperature": 5,
"max_new_tokens": 500,
"retrieval_details": true
}
optional_parameters
Hiermit kann man optionale Parameter, die nicht von allen LLMs unterstützt werden, übergeben.
Name | Beschreibung | Unterstützte LLM Protokolle |
do_sample | Wenn do_sample auf false gesetzt ist, erfolgt die Textgenerierung deterministisch. Das Modell wählt immer das Token mit der höchsten Wahrscheinlichkeit (logits-Wert). Diese Einstellung wird empfohlen für klar definierte und vorhersehbare Aufgaben. Wenn do_sample auf true gesetzt ist, erfolgt die Auswahl der nächsten Tokens stochastisch, basierend auf den Wahrscheinlichkeitsverteilungen, die das Modell berechnet. Dies ermöglicht kreativere und diversere Ausgaben. Typ: Boolean | InSpire LLM |
truncate | Kürzt die Anzahl der Token auf die angegebene Größe. Das Definieren dieser Einstellung ist sinnvoll für das Einhalten der Kontextgröße bei LLMs. Die Konfiguration dieser Einstellung wird empfohlen, wenn davon auszugehen ist, dass sehr lange Prompts verwendet werden, die eventuell auch die Kontextlänge des LLMs überschreiten könnten. Typ: Integer Achtung: Durch die Verwendung des „truncate“ Parameters können Informationen verloren gehen. | InSpireLLM |
{
"do_sample": true,
"truncate": 8000
}
prompt_dictionary
Optional können zum Ausfüllen von Platzhaltern in der Prompt Template der verwendeten Pipeline Key- Value Paare angegeben werden. Um Default Platzhalter zu überschreiben, muss die Einstellung „Überschreiben von Systemprompttemplatevariablen zulassen“ in der Pipeline aktiviert sein.
"prompt_dictionary": {
"question": "Tell me about Mindbreeze",
"answer": "Mindbreeze is fast!"
}
retrieval_options
Optional können die Retrieval-Einstellungen der verwendeten Pipeline überschrieben werden.
constraint | Query Expression, die zusätzlich zu der in der Pipeline konfigurierten Sucheinschränkung für das Retrieval verwendet wird. Type: String |
search_request | Erweitert die Suchanfrage, die für das Retrieval verwendet wird. Felder dich nicht in der Suchanfrage der Pipeline vorhanden sind, werden ergänzt, um das Überschreiben von Feldern zu erlauben, muss die Einstellung „Überschreiben der Suchanfragenvorlage erlauben“ in der Pipeline aktiviert sein. Type: Objekt Für mehr Informationen, siehe api.v2.search Schnittstellenbeschreibung - Felder in der Suchanfrage. |
use_inputs | Steuert, ob der Eingabetext (inputs) als Query für das Retrieval verwendet wird. Standardwert: true Type: Boolean |
skip_retrieval | Überspringt den Retrieval Teil. Diese Einstellung ist hilfreich, wenn man ohne einen zusätzlichen Kontext aus Antworten generieren möchte oder die Antworten selbst angeben möchte. Standardwert: false Type: Boolean Für mehr Informationen, siehe die Einstellung „answers“ im Kapitel generation_options. |
"retrieval_options": {
"constraint": {
"unparsed": "title:management"
},
"search_request": {
"term": "mind"
},
"use_inputs": false,
"skip_retrieval": true
}
generation_options
Optional können die Retrieval-Einstellungen der verwendeten Pipeline überschrieben werden:
Dieses „Prompt Dictionary“ hat Priorität gegenüber dem anderen prompt_dictionary. Für mehr Informationen, siehe das Kapitel prompt_dictionary | |
llm_selector | Mit dieser Einstellung kann ein LLM für die Generierung via Namen oder Familie ausgewählt werden. Dies ist nur möglich, wenn keine Pipeline mit model_id spezifiziert wurde. Die Werte der einzelnen LLMs können über die /data Schnittstelle herausgefunden werden. |
answers | Mit dieser Einstellung kann man die Antworten selbst angeben, vorausgesetzt das Retrieval wurde mit skip_retrieval in den retrieval_options deaktiviert. Type: List[Answer] Für mehr Informationen, siehe api.v2.search Schnittstellenbeschreibung - answers. |
message_templates | Mit dieser Einstellung können die Messages, die an das LLM geschickt werden sollen, sehr präzise angegeben werden. Für mehr Informationen, siehe das Kapitel message_templates [Liste]. |
"generation_options": {
"prompt_dictionary": {
"company": "Mindbreeze"
},
"llm_selector": {
"family": "Meta Llama 3 Instruct"
}
}
message_templates [Liste]
Definiert die Rolle des Konversationsteilnehmers dieser Message. Mögliche Werte sind:
Type: String | |
content | Der Inhalt der Message, der aus mehreren Teilen bestehen kann. Für mehr Infomationen, siehe das Kapitel content [Liste]. |
{
"role": "user",
"content": [
{
"type": "text",
"text": "Who is the CEO of Mindbreeze?"
}
]
}
content [Liste]
Definiert den Typ dieses Inhalts. Mögliche Werte sind: text text/fstring-template Type: String | |
text | Definiert den eigentlichen Inhalt. Wenn die Einstellung type den Wert text/fstring-template besitzt, können hier Platzhalter aus der Einstellung prompt_dictionary oder die Standardplatzhalter (summaries und question) verwendet werden. Type: String |
{
"type": "text/fstring-template",
"text": "You are a helpful AI assistant. Please answer the question with the context below:\n{summaries}"
}
Felder in der Response
Die Struktur ist abhängig vom Feld „stream“ im Request.
stream (Request) | Response Struktur |
true (Default) | TokenStreamEvent |
false | GeneratTextResponse |
TokenStreamEvent
Beim Streaming enthält nur das letzte TokenStreamEvent den kompletten generierten Text.
data: {"token": {"text": "Daniel", "logprob": -0.055236816, "id": 4173}}
data: {"token": {"text": " ", "logprob": -0.0005774498, "id": 32106}}
data: {"token": {"text": "Fall", "logprob": -7.176399e-05, "id": 2589}}
…
"data": {
"token":{
"text":"</s>",
"logprob":-0.22509766,
"id":1,
"special":true
},
"generated_text":"Daniel Fallmann is the CEO of Mindbreeze.\n\nRetrieved Sources: …",
"details":{
"finish_reason":"eos_token",
"generated_tokens":19.0,
"seed":null
},
"content_processed":"Given the following …"
}
token
Enthält Informationen zum generierten Token
text | Textinhalt des Tokens. Type: String |
logprob | Logarithmische Wahrscheinlichkeit des Tokens. Type: Float ]-inf,0] |
id | Kennung des Tokens in Bezug auf seinen Kontext Type: Integer |
special | Token hat spezielle Bedeutung (e.g. End-of-Sequence). Type: Boolean |
"token": {
"text": "mind",
"logprob": -0.0029792786,
"id": 1,
"special": false
}
generated_text [String]
Der komplette generierte Text, also alle gestreamten Tokens, ausgenommen Special Tokens.
"generated_text": "The CEO of Mindbreeze is…",
details
finish_reason | Grund für den Abschluss der Token-Generierung (z.B. "eos_token"). Type: String |
generated_tokens | Anzahl der generierten Tokens. Type: Float |
seed | Bei der Generierung verwendeter Seed. Type: String | null |
"details": {
"finish_reason": "eos_token",
"generated_tokens": 51.0,
"seed": null
}
content_processed [String]
Enthält den Text, der als Eingabe zur Generierung an das LLM gesendet wurde (Prompt). Der Text wird anhand der Prompt Template der Verwendeten Pipeline erzeugt.
"content_processed": "Given the following extracted parts of …"
retrieval_details
Enthält Informationen zu den erhaltenen Antworten der Suche. Nur präsent, wenn der Parameter "retrieval_details" mit "true" im Request mitgeschickt wurde.
answers | Die Liste der Antworten aus der Suche. Type: List[Answer] Für mehr Informationen, siehe api.v2.search Schnittstellenbeschreibung - Antwort. |
GenerateTextResponse
Ohne Streaming wird der generierte Text, ohne zusätzlich Informationen wie beim Streaming zurückgeliefert.
"generated_text": "Daniel Fallmann is the CEO…",
"details": {
"generated_tokens": 19,
"tokens": [
{
"text": "Daniel",
"logprob": -0.055236816
},
{
"text": " ",
"logprob": -0.0005774498
},
{
"text": "Fall",
"logprob": -7.176399e-05
},
…
{
"text": "</s>",
"logprob": -0.22509766,
"special":true
}
]
},
"retrieval_details" {
"answers": [
{
"score": 0.7742171883583069,
"text": {
"text": "Management \nDaniel Fallmann Founder & CEO\nDaniel Fallmann founded Mindbreeze in 2005 and as its CEO he is a living example of high quality and innovation standards.",
"context_after": " From the company’s very beginning, Fallmann, together with his team, laid the foundation for the highly scalable and intelligent Mindbreeze InSpire appliance.",
"text_start_pos": 0,
"text_end_pos": 164
},
"property_name": "content",
"properties": [
{
"id": "extension",
"name": "Extension",
"data": [
{
"value": {
"str": "html"
}
}
]
},
...
]
}
]
}
}
generated_text [String]
Der komplette generierte Text, also alle gestreamten Tokens, ausgenommen Special Tokens.
"generated_text": "The CEO of Mindbreeze is…",
details
Enthält Informationen zum generierten Text. Nur präsent, wenn der Parameter "details" mit "true" im Request mitgeschickt wurde.
generated_tokens | Anzahl der generierten Tokens. Type: Integer |
tokens | Die generierten Tokens Type: Array[Token] |
token
Enthält Informationen zum generierten Token
text | Textinhalt des Tokens. Type: String |
logprob | Logarithmische Wahrscheinlichkeit des Tokens. Type: Float ]-inf,0] |
retrieval_details
Enthält Informationen zu den erhaltenen Antworten der Suche. Nur präsent, wenn der Parameter "retrieval_details" mit "true" im Request mitgeschickt wurde.
answers | Die Liste der Antworten aus der Suche. Type: List[Answer] Für mehr Informationen, siehe api.v2.search Schnittstellenbeschreibung - Antwort. |