Adds examples to chat completion inference API (#4346) (#4348)

* Adds examples to chat completion inference API.

* Fixes format.

(cherry picked from commit b407c71)

Co-authored-by: István Zoltán Szabó <szabosteve@gmail.com>

Author: github-actions[bot]

specification/inference/_types/CommonTypes.ts

@@ -25,6 +25,8 @@ import { float, integer, long } from '@_types/Numeric'
 export class RequestChatCompletion {
   /**
    * A list of objects representing the conversation.
+   * Requests should generally only add new messages from the user (role `user`).
+   * The other message roles (`assistant`, `system`, or `tool`) should generally only be copied from the response to a previous completion request, such that the messages array is built up throughout a conversation.
    */
   messages: Array<Message>
   /**

specification/inference/chat_completion_unified/UnifiedRequest.ts

@@ -23,6 +23,17 @@ import { Id } from '@_types/common'
 import { Duration } from '@_types/Time'
 /**
  * Perform chat completion inference
+ * 
+ * The chat completion inference API enables real-time responses for chat completion tasks by delivering answers incrementally, reducing response times during computation. 
+ * It only works with the `chat_completion` task type for `openai` and `elastic` inference services.
+
+ * IMPORTANT: The inference APIs enable you to use certain services, such as built-in machine learning models (ELSER, E5), models uploaded through Eland, Cohere, OpenAI, Azure, Google AI Studio, Google Vertex AI, Anthropic, Watsonx.ai, or Hugging Face.
+ * For built-in models and models uploaded through Eland, the inference APIs offer an alternative way to use and manage trained models. However, if you do not plan to use the inference APIs to use these models or if you want to use non-NLP models, use the machine learning trained model APIs.
+ * 
+ * NOTE: The `chat_completion` task type is only available within the _stream API and only supports streaming.
+ * The Chat completion inference API and the Stream inference API differ in their response structure and capabilities.
+ * The Chat completion inference API provides more comprehensive customization options through more fields and function calling support.
+ * If you use the `openai` service or the `elastic` service, use the Chat completion inference API.
  * @rest_spec_name inference.chat_completion_unified
  * @availability stack since=8.18.0 stability=stable visibility=public
  * @availability serverless stability=stable visibility=public

specification/inference/chat_completion_unified/examples/request/PostChatCompletionRequestExample1.yaml

@@ -0,0 +1,14 @@
+summary: A chat completion task
+description: Run `POST _inference/chat_completion/openai-completion/_stream` to perform a chat completion on the example question with streaming.
+# method_request: "POST _inference/chat_completion/openai-completion/_stream"
+# type: "request"
+value: |-
+  {
+    "model": "gpt-4o",
+    "messages": [
+        {
+            "role": "user",
+            "content": "What is Elastic?"
+        }
+    ]
+  }

specification/inference/chat_completion_unified/examples/request/PostChatCompletionRequestExample2.yaml

@@ -0,0 +1,28 @@
+summary: A chat completion task with tool_calls
+description: Run `POST POST _inference/chat_completion/openai-completion/_stream` to perform a chat completion using an Assistant message with `tool_calls`.
+# method_request: "POST _inference/chat_completion/openai-completion/_stream"
+# type: "request"
+value: |-
+  {
+    "messages": [
+        {
+            "role": "assistant",
+            "content": "Let's find out what the weather is",
+            "tool_calls": [ 
+                {
+                    "id": "call_KcAjWtAww20AihPHphUh46Gd",
+                    "type": "function",
+                    "function": {
+                        "name": "get_current_weather",
+                        "arguments": "{\"location\":\"Boston, MA\"}"
+                    }
+                }
+            ]
+        },
+        { 
+            "role": "tool",
+            "content": "The weather is cold",
+            "tool_call_id": "call_KcAjWtAww20AihPHphUh46Gd"
+        }
+    ]
+  }

specification/inference/chat_completion_unified/examples/request/PostChatCompletionRequestExample3.yaml

@@ -0,0 +1,41 @@
+summary: A chat completion task with tools and tool_calls
+description: Run `POST POST _inference/chat_completion/openai-completion/_stream` to perform a chat completion  using a User message with `tools` and `tool_choice`.
+# method_request: "POST _inference/chat_completion/openai-completion/_stream"
+# type: "request"
+value: |-
+  {
+    "messages": [
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "text",
+                    "text": "What's the price of a scarf?"
+                }
+            ]
+        }
+    ],
+    "tools": [
+        {
+            "type": "function",
+            "function": {
+                "name": "get_current_price",
+                "description": "Get the current price of a item",
+                "parameters": {
+                    "type": "object",
+                    "properties": {
+                        "item": {
+                            "id": "123"
+                        }
+                    }
+                }
+            }
+        }
+    ],
+    "tool_choice": {
+        "type": "function",
+        "function": {
+            "name": "get_current_price"
+        }
+    }
+  }

specification/inference/chat_completion_unified/examples/response/PostChatCompletionResponseExample1.yaml

@@ -0,0 +1,21 @@
+# summary:
+description: A successful response when performing a chat completion task using a User message with `tools` and `tool_choice`.
+# type: response
+# response_code: 200
+value: |-
+  event: message
+  data: {"chat_completion":{"id":"chatcmpl-Ae0TWsy2VPnSfBbv5UztnSdYUMFP3","choices":[{"delta":{"content":"","role":"assistant"},"index":0}],"model":"gpt-4o-2024-08-06","object":"chat.completion.chunk"}}
+
+  event: message
+  data: {"chat_completion":{"id":"chatcmpl-Ae0TWsy2VPnSfBbv5UztnSdYUMFP3","choices":[{"delta":{"content":Elastic"},"index":0}],"model":"gpt-4o-2024-08-06","object":"chat.completion.chunk"}}
+
+  event: message
+  data: {"chat_completion":{"id":"chatcmpl-Ae0TWsy2VPnSfBbv5UztnSdYUMFP3","choices":[{"delta":{"content":" is"},"index":0}],"model":"gpt-4o-2024-08-06","object":"chat.completion.chunk"}}
+
+  (...)
+
+  event: message
+  data: {"chat_completion":{"id":"chatcmpl-Ae0TWsy2VPnSfBbv5UztnSdYUMFP3","choices":[],"model":"gpt-4o-2024-08-06","object":"chat.completion.chunk","usage":{"completion_tokens":28,"prompt_tokens":16,"total_tokens":44}}} 
+
+  event: message
+  data: [DONE]