URI: /api/conversation/v1/exchange-events/sse
CreateExchangeEventSSE
The CreateExchangeEventSSE streams text generation events as they arrive with data-only Server-Sent Events (SSE). This creates a record of a verbal/textual interaction, that is, the combination of an input audio/text and an output audio/text and allows instantaneous partial results to display from the model as the full generation progresses. Each exchange targets only one knowledge domain. Each message is sent within a second or less, and the reduced latency of the streaming query responses enhances the end-user experience.
Messages for a single streaming request are sent in the following sequence:
- Clients establish a connection to the service by issuing a POST request to the /api/conversation/v1/exchange-events/sse endpoint
- The server processes the request and sends a response with a 200 OK status code, Content-Type header set to text/event-stream.
When creating a streaming request, you can override the collection configuration using the following configuration parameters, which are defined in the following table:
- randomness
- max_answer_in_contexts_num
- min_answer_in_contexts_score
- answer_in_contexts_beam_delta_cutoff
- verified_answer_score_threshold
- out_of_domain_score_threshold
- out_of_domain_message
Input model
| Field Name | Type | Description | Example Value |
|
conversation_id optional |
string | The conversation_id value returned in the prior CreateExchangeResponse. Omitting conversation_id will start a new conversation on the request. | 2204dpad-ea7f-11a8-b7e3-999251427254 |
|
audio_output_enabled optional |
boolean | If set to true, the system responds with available audio output. When audio output can't be generated, successful exchange responses include only text output. Default is false. | false |
| knowledge_domain_id | string | Version of a collection. If not defined, the active version of the collection is automatically used. If both knowledge_domain_id and collection_id are set, the exchange operation will use knowledge_domain_id as the more specific of the two. | 5572cd8-65e9-46y7-9733-d2d7d123zz5z |
|
max_outputs |
int32 | Specifies the number of outputs to be returned (min 3, max 10). Default is 3. | 3 |
|
collection_id required |
string | The knowledge collection, or index, that the exchange is performed against. The exchange operation automatically determines and uses the active version of this collection. | 2204dpad-b3f8-46y7-h944-0000a8f4bd9d |
|
max_sentence_outputs optional |
int32 | Specifies the number of sentence spans to be returned per top-level output (min 1, max 10). Default is 1. | 1 |
|
max_concise_outputs optional |
int32 | Specifies the number of concise spans to be returned per top-level output (min 1, max 10). Default is 1. | 1 |
|
content_group_ids optional |
array | Specifies the content groups used to return data. | ['ddd143cc-0582-46bc-875e-91b89ed99111', 'ddd143cc-0582-46bc-875e-91b89ed99112'] |
|
subject_ids optional |
array of strings | Specifies the subjects used to return data. | ['9898cde2-8191-ab14-aaaa-0011a8f4bd9d', '9898cde2-8191-ab14-aaaa-0011a8f4bd9c'] |
| condition | string |
Filter conditions are written as strings. A single comparable condition is written as
You can combine conditions with AND, OR operators. For example, (Star = 'Harrison Ford' AND (Creator = 'George Lucas' OR Director = 'Steven Spielberg')) |
"input": {"option": {"filter": {"condition": "(Star = 'Harrison Ford' AND (Creator = 'George Lucas' OR Director = 'Steven Spielberg'))}}}" |
| fields | object | Unordered map of dynamically typed values. | "input": {"option": {"context": {"fields": {"custom_field1": {"number_value": 100.00}, "custom_field2": {"string_value": "string value here"}}}}} |
| language_id | string |
The default is en-US. |
en-US |
|
raw_text required |
string | Input query used for retrieval. | What is Pryon? |
|
audio_encoding optional |
enum |
Audio encoding of the content in the message.
Default: UNSPECIFIED_AUDIO_ENCODING
Enum: UNSPECIFIED_AUDIO_ENCODING
LINEAR16 MP3
|
LINEAR16 |
|
sample_rate_hertz optional |
int32 | Sample rate in Hertz of the audio data. The only valid value currently supported is 16000, which must be explicitly stated by the client. | 16000 |
|
content optional |
byte | The bytes of audio data encoded as specified in audio_encoding. | c3RyaW5n |
|
recommended_questions optional |
enum |
Request additional questions to be recommended alongside the response when applicable. RELATED: Request only related questions FOLLOWUP: Request only follow-up questions RELATED_AND_FOLLOWUP: Request both related and follow-up questions. |
RELATED |
Input model configuration parameters
| Field Name | Type | Description | Example Value |
|
randomness optional |
<number> float |
Controls the randomness of the generated text, ranging from 0 to 1. Higher values result in more random text, while lower values produce more focused and deterministic text. The default value is 0, promoting deterministic and repetitive generative text. |
0
|
|
max_answer_in_contexts_num optional |
int32 | Determines the maximum number of the ExchangeOutput answer_in_contexts to be considered when generating a response. The value must be greater than 0. The default value is 3. | 3 |
|
min_answer_in_contexts_score optional |
<number> float | Sets the minimum score of the ExchangeOutput answer_in_contexts to be considered when generating a response. The value must be between 0 and 1. The default value is 0.55. | 0.55 |
|
answer_in_contexts_beam_delta_cutoff optional |
<number> float | A maximum allowable answer_in_context score delta from the highest score to be considered when generating a response. The value must be between 0 and 1. The default value is set to 0.1. | 0.1 |
|
verified_answer_score_threshold optional |
<number> float | Threshold of verified answer to be considered as a final answer. The value must be between 0 and 1. The default value is 0.55. | 0.55 |
|
out_of_domain_score_threshold optional |
<number> float | Threshold of best answer score which out of domain message should be returned as a final answer. The value must be between 0 and 1. The default value is 0.55. | 0.55 |
|
out_of_domain_message optional |
string | The message to be used as a final answer when the input query is out of domain. The given knowledge collections do not provide any information on your question. | Could you please clarify your question? |
|
conversation_context optional |
string | Obtained from the previous response, this enhances the generative response. |
This field is initially empty and the context is returned from the LLM in each response. The context must be included in subsequent requests for multi-turn conversations, and is an iterative value that adjusts over time. 05de10ee-892b-3b3e-9e8d-1318d7c71ac0~511734eb-c68f-4b51-94e9-d8216465cd6f\n---end-of-context---\nwhat is a knot stopper?\n A stopper knot serves to create a bulging, secure point on a rope that maintains a consistent thickness, thus preventing the rope from slipping through tight spaces like holes in blocks. Passing a rope through such an opening is referred to as reeving it. |
Request sample
Show code
{
"input": {
"option": {
"audio_output_enabled": true,
"max_outputs": 10,
"collection_id": "2204dpad-b3f8-46y7-h944-0000a8f4bd9d"
},
"raw_text": "How old is Yoda?"
},
"randomness": 0,
"max_answer_in_contexts_num": 3,
"min_answer_in_contexts_score": 0.55,
"answer_in_contexts_beam_delta_cutoff": 0.1,
"verified_answer_score_threshold": 0.55,
"out_of_domain_score_threshold": 0.55,
"out_of_domain_message": "The given knowledge collections
do not provide any information on your question. Could you
please clarify your question?"
}
Basic streaming event responses
GENERATIVE_EXCHANGE_INPUT_DELTA
Token by token generated by the LLM to refine the user query.
Show code
{
"state": "GENERATIVE_EXCHANGE_INPUT_DELTA",
"exchange_input_text": "How"
}
{
"state": "GENERATIVE_EXCHANGE_INPUT_DELTA",
"exchange_input_text": " old"
}
{
"state": "GENERATIVE_EXCHANGE_INPUT_DELTA",
"exchange_input_text": " is"
}
{
"state": "GENERATIVE_EXCHANGE_INPUT_DELTA",
"exchange_input_text": " Yoda?"
}
GENERATIVE_EXCHANGE_INPUT_COMPLETE
The accumulated DELTA event strings, for example, GENERATIVE_EXCHANGE_INPUT_DELTA events are complete.
Show code
{
"metadata": {
"uuid": "9c5ca545-88a2-4c5a-b712-ff44a57245d5",
"create_time": "2023-05-15T11:50:47.982459Z",
"update_time": "2023-05-15T11:50:47.982459Z"
},
"state": "GENERATIVE_EXCHANGE_INPUT_COMPLETE",
"exchange_input_text": "How old is Yoda?"
}
EXCHANGE_RESPONSE_COMPLETE
CreateExchange() API response.
Show code
{
"metadata": {
"uuid": "9c5ca545-88a2-4c5a-b712-ff44a57245d5",
"create_time": "2023-05-15T11:50:48.831492Z",
"response_time_millis": 2615
},
"state": "EXCHANGE_RESPONSE_COMPLETE",
"exchange_response_data": {
"exchange_id": "abe96862-7700-4547-978d-213085d1e1cc",
"conversation_id": "511734eb-c68f-4b51-94e9-d8216465cd6f",
"normalized_input": {
"normalized_input_id": "7bbf4c9b-da3c-491b-87c5-f665f676c9eb",
"raw_text": "How old is Yoda?",
"understood_text": "How old is Yoda?"
},
"output": [
{
"output_id": "best_1",
"text": " Yoda was an astute and able Jedi Master
in the Star Wars stories. He lived a continued life,
authoritatively 900 years old. This shows how long his
species can live. Yoda spent his activity teaching an
allegorical adolescent Jedi, like Luke Skywalker.",
"attachments": {
"answer_in_context": {
"content_type": "application/vnd.pryon.answer_in_context",
"content": "Yoda was an astute and able Jedi Master
in the Star Wars stories. He lived a continued life,
authoritatively 900 years old. This shows how long his
species can live. Yoda spent his activity teaching an
allegorical adolescent Jedi, like Luke Skywalker."
},
"score": {
"content_type": "application/vnd.pryon.score",
"content": "0.6804"
},
...
..
.
},
...
..
.
]
}
}
GENERATIVE_EXCHANGE_RESPONSE_DELTA
Token by token generated by LLM to refine the CreateExchange() response.
Show code
{
"state": "GENERATIVE_EXCHANGE_RESPONSE_DELTA",
"generative_exchange_conversation_data": {
"data": {
"text": "Yoda"
}
}
}
{
"state": "GENERATIVE_EXCHANGE_RESPONSE_DELTA",
"generative_exchange_conversation_data": {
"data": {
"text": " is"
}
}
}
{
"state": "GENERATIVE_EXCHANGE_RESPONSE_DELTA",
"generative_exchange_conversation_data": {
"data": {
"text": " 900"
}
}
}
{
"state": "GENERATIVE_EXCHANGE_RESPONSE_DELTA",
"generative_exchange_conversation_data": {
"data": {
"text": " years"
}
}
}
{
"state": "GENERATIVE_EXCHANGE_RESPONSE_DELTA",
"generative_exchange_conversation_data": {
"data": {
"text": " old."
}
}
}
GENERATIVE_EXCHANGE_RESPONSE_COMPLELTE
The accumulated strings of DELTA events, for example, GENERATIVE_EXCHANGE_RESPONSE_DELTA events are complete. Responses from this state will also contain conversation_contexts to be used for the next turn.
Show code
{
"metadata": {
"uuid": "9c5ca545-88a2-4c5a-b712-ff44a57245d5",
"create_time": "2023-05-15T11:50:56.395538Z",
"update_time": "2023-05-15T11:50:56.395538Z",
"response_time_millis": 10179
},
"state": "GENERATIVE_EXCHANGE_RESPONSE_COMPLELTE",
"generative_exchange_conversation_data": {
"data": {
"text": "Yoda is 900 years old.",
"reference": [
{
"text_index_start": 24,
"text_index_end": 26,
"exchange_output_index": 1
}
]
},
"conversation_context": "05de10ee-892b-3b3e-9e8d-1318d7c71ac0~511734eb-c68f-
4b51-94e9-d8216465cd6f\n---end-of-context---\nwhere did yoda live?\n Home to
Yoda during his final years, Dagobah was a swamp-covered planet strong with the
Force -- a forgotten world where the wizened Jedi Master could escape the notice
of Imperial forces. Characterized by its bog-like conditions and fetid wetlands,
the murky and humid quagmire was undeveloped, with no signs of technology."
}
}