From be7544c4237e2b83d59bc706f12da36c018641d1 Mon Sep 17 00:00:00 2001 From: Christian Tzolov Date: Sun, 21 Jul 2024 11:56:53 +0200 Subject: [PATCH] Improve Message docs --- .../azure-open-ai-chat-functions.adoc | 2 - .../modules/ROOT/pages/api/chatmodel.adoc | 44 ++++++----- .../antora/modules/ROOT/pages/api/prompt.adoc | 74 ++++++++----------- 3 files changed, 53 insertions(+), 67 deletions(-) diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/functions/azure-open-ai-chat-functions.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/functions/azure-open-ai-chat-functions.adoc index 0ffd7f999..6c4d38b12 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/functions/azure-open-ai-chat-functions.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chat/functions/azure-open-ai-chat-functions.adoc @@ -6,8 +6,6 @@ You can register custom Java functions with the `AzureOpenAiChatModel` and have This allows you to connect the LLM capabilities with external tools and APIs. The Azure models are trained to detect when a function should be called and to respond with JSON that adheres to the function signature. -NOTE: Parallel function calling is only supported with gpt-35-turbo (1106) and gpt-4 (1106-preview) also known as GPT-4 Turbo Preview. - The Azure OpenAI API does not call the function directly; instead, the model generates JSON that you can use to call the function in your code and return the result back to the model to complete the conversation. Spring AI provides flexible and user-friendly ways to register and call custom functions. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatmodel.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatmodel.adoc index 560c3cbdb..b754b21de 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatmodel.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatmodel.adoc @@ -74,35 +74,39 @@ public class Prompt implements ModelRequest> { ==== Message -The `Message` interface encapsulates a textual message, a collection of attributes as a `Map`, and a categorization known as `MessageType`. The interface is defined as follows: +The `Message` interface encapsulates a Prompt textual content and a collection of metadata attributes and a categorization known as `MessageType`. -[source,java] ----- -public interface Message extends Node { - - String getContent(); - - List getMedia(); - - MessageType getMessageType(); -} ----- - - -and the Node interface is +The interface is defined as follows: ```java +public interface Content { -public interface Node { + String getContent(); - T getContent(); + Map getMetadata(); +} - Map getMetadata(); +public interface Message extends Content { + + MessageType getMessageType(); } ``` -The `Message` interface has various implementations that correspond to the categories of messages that an AI model can process. -Some models, like OpenAI's chat completion endpoint, distinguish between message categories based on conversational roles, effectively mapped by the `MessageType`. +The multimodal message types implement also the `MediaContent` interface providing a list of `Media` content objects. + +```java +public interface MediaContent extends Content { + + Collection getMedia(); + +} +``` + +The `Message` interface has various implementations that correspond to the categories of messages that an AI model can process: + +image::spring-ai-message-api.jpg[Spring AI Message API, width=800, align="center"] + +The chat completion endpoint, distinguish between message categories based on conversational roles, effectively mapped by the `MessageType`. For instance, OpenAI recognizes message categories for distinct conversational roles such as `system`,`user`, `function` or `assistant`. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/prompt.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/prompt.adoc index dc9c873b3..d12b51439 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/prompt.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/prompt.adoc @@ -44,55 +44,57 @@ public class Prompt implements ModelRequest> { === Message -The `Message` interface encapsulates a textual message, a collection of attributes as a `Map`, a categorization known as `MessageType`, and a list of media objects for those models that are multimodal. +The `Message` interface encapsulates a Prompt textual content and a collection of metadata attributes and a categorization known as `MessageType`. + The interface is defined as follows: -image::spring-ai-message-api.jpg[Spring AI Message API, width=800, align="center"] - ```java -public interface Message extends Content { - - MessageType getMessageType(); - -} -``` - -and the Content interface is - -```java - public interface Content { String getContent(); Map getMetadata(); } + +public interface Message extends Content { + + MessageType getMessageType(); +} ``` -Various implementations of the `Message` interface correspond to different categories of messages that an AI model can process. Some models, like those from OpenAI, distinguish between message categories based on conversational roles. These roles are effectively mapped by the `MessageType`, as discussed below. +The multimodal message types implement also the `MediaContent` interface providing a list of `Media` content objects. +```java +public interface MediaContent extends Content { -== Roles + Collection getMedia(); -The evolution of prompts in AI has transitioned from basic, straightforward text to more organized and complex formats with specific roles and structures. +} +``` -Initially, prompts were simple strings – just lines of text. -Over time, this evolved to include specific placeholders within these strings, like “USER:”, which the AI model could recognize and respond to accordingly. -This was a step towards more structured prompts. +Various implementations of the `Message` interface correspond to different categories of messages that an AI model can process. +The Models distinguish between message categories based on conversational roles. -OpenAI then introduced an even more organized approach. -In their model, prompts are not merely single strings but a series of messages. -Each message, while still in text form, is assigned a specific role. +image::spring-ai-message-api.jpg[Spring AI Message API, width=800, align="center"] + +These roles are effectively mapped by the `MessageType`, as discussed below. + +==== Roles + +Each message is assigned a specific role. These roles categorize the messages, clarifying the context and purpose of each segment of the prompt for the AI model. This structured approach enhances the nuance and effectiveness of communication with the AI, as each part of the prompt plays a distinct and defined role in the interaction. - The primary roles are: * System Role: Guides the AI's behavior and response style, setting parameters or rules for how the AI interprets and replies to the input. It's akin to providing instructions to the AI before initiating a conversation. * User Role: Represents the user's input – their questions, commands, or statements to the AI. This role is fundamental as it forms the basis of the AI's response. -* Assistant Role: The AI's response to the user's input. More than just an answer or reaction, it's crucial for maintaining the flow of the conversation. By tracking the AI's previous responses (its 'Assistant Role' messages), the system ensures coherent and contextually relevant interactions. -* Function Role: This role deals with specific tasks or operations during the conversation. While the System Role sets the AI's overall behavior, the Function Role focuses on carrying out certain actions or commands the user asks for. It's like a special feature in the AI, used when needed to perform specific functions such as calculations, fetching data, or other tasks beyond just talking. This role allows the AI to offer practical help in addition to conversational responses. +* Assistant Role: The AI's response to the user's input. +More than just an answer or reaction, it's crucial for maintaining the flow of the conversation. +By tracking the AI's previous responses (its 'Assistant Role' messages), the system ensures coherent and contextually relevant interactions. +The Assistant message may contain Function Tool Call request information as well. +It's like a special feature in the AI, used when needed to perform specific functions such as calculations, fetching data, or other tasks beyond just talking. +* Tool/Function Role: The Too/Function Role focuses on returning additional information in response to Tool Call Aisstnat Messages. Roles are represented as an enumeration in Spring AI as shown below @@ -107,25 +109,7 @@ public enum MessageType { TOOL("tool"); - private final String value; - - MessageType(String value) { - this.value = value; - } - - public String getValue() { - return value; - } - - public static MessageType fromValue(String value) { - for (MessageType messageType : MessageType.values()) { - if (messageType.getValue().equals(value)) { - return messageType; - } - } - throw new IllegalArgumentException("Invalid MessageType value: " + value); - } - + ... } ```