diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc index 747026606..be42870da 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/chatclient.adoc @@ -34,8 +34,9 @@ public interface ChatClient { The `generate` method with a `String` parameter simplifies initial use, avoiding the complexities of the more sophisticated `Prompt` and `AiResponse` classes. +In real-world applications, it is more common to use the `generate` method that takes a `Prompt` instance and returns an `AiResponse`. + === Prompt -In a real-world application, it is most common to use the `generate` method, taking a `Prompt` instance and returning an `AiResponse`. The `Prompt` class encapsulates a list of `Message` objects. The following listing shows a truncated version of the Prompt class, excluding constructors and other utility methods: @@ -69,7 +70,7 @@ The `Message` interface has various implementations that correspond to the categ Some models, like OpenAI's 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,`" or "`assistant.`" -While the term, `MessageType`, might imply a specific message format, in this context, it effectively designates the role a message plays in the dialogue. +While the term `MessageType` might imply a specific message format, in this context it effectively designates the role a message plays in the dialogue. For AI models that do not use specific roles, the `UserMessage` implementation acts as a standard category, typically representing user-generated inquiries or instructions. To understand the practical application and the relationship between `Prompt` and `Message`, especially in the context of these roles or message categories, see the detailed explanations in the xref:api/prompt.adoc[Prompts] section. @@ -87,7 +88,7 @@ public class AiResponse { } ``` -The `AiResponse` class holds the AI Model's output, with each `Generation` instance containing one of potentially multiple outputs from a single prompt. +The `AiResponse` class holds the AI Model's output, with each `Generation` instance containing one of potentially multiple outputs resulting from a single prompt. The `AiResponse` class also carries a map of key-value pairs providing metadata about the AI Model's response. This feature is still in progress and is not elaborated on in this document. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/azure-openai.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/azure-openai.adoc index f9b99fd9e..4a6fe0788 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/azure-openai.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/clients/azure-openai.adoc @@ -5,7 +5,7 @@ Azure's OpenAI offering, powered by ChatGPT, extends beyond traditional OpenAI c Azure offers Java developers the opportunity to leverage AI's full potential by integrating it with an array of Azure services, which includes AI-related resources such as Vector Stores on Azure. -== Gettting Started +== Getting Started Obtain your Azure OpenAI `endpoint` and `api-key` from the Azure OpenAI Service section on the link:https://portal.azure.com[Azure Portal]. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings.adoc index ef7da7bf2..663089c30 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings.adoc @@ -21,8 +21,7 @@ This section provides a guide to the `EmbeddingClient` interface and associated === EmbeddingClient Here is the `EmbeddingClient` interface definition: -java -Copy code +```java public interface EmbeddingClient { List embed(String text); @@ -36,9 +35,10 @@ public interface EmbeddingClient { default int dimensions() { return embed("Test String").size(); } - } -The embed methods offer various options for converting text into embeddings, accommodating single strings, structured Document objects, or batches of text. +``` + +The embed methods offer various options for converting text into embeddings, accommodating single strings, structured `Document` objects, or batches of text. The returned values are lists of doubles, representing the embeddings in a numerical vector format. The `embedForResponse` method provides a more comprehensive output, potentially including additional information about the embeddings. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/onnx.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/onnx.adoc index 4dbb91113..722fb3b7f 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/onnx.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/onnx.adoc @@ -1,6 +1,6 @@ = ONNX -The `TransformersEmbeddingClient` is an `EmbeddingClient` implementation that computes, locally, https://www.sbert.net/examples/applications/computing-embeddings/README.html#sentence-embeddings-with-transformers[sentence embeddings] using a selected https://www.sbert.net/[sentence transformer]. +The `TransformersEmbeddingClient` is an `EmbeddingClient` implementation that locally computes https://www.sbert.net/examples/applications/computing-embeddings/README.html#sentence-embeddings-with-transformers[sentence embeddings] using a selected https://www.sbert.net/[sentence transformer]. It uses https://www.sbert.net/docs/pretrained_models.html[pre-trained] transformer models, serialized into the https://onnx.ai/[Open Neural Network Exchange (ONNX)] format. @@ -14,7 +14,7 @@ To run things in Java, we need to serialize the Tokenizer and the Transformer Mo One, quick, way to achieve this, is to use the https://huggingface.co/docs/optimum/exporters/onnx/usage_guides/export_a_model#exporting-a-model-to-onnx-using-the-cli[optimum-cli] command line tool. -Following snippet prepares a python virtual environment, installs the required packages and serializes (e.g. exports) specified model using `optimum-cli` : +The following snippet prepares a python virtual environment, installs the required packages and serializes (e.g. exports) the specified model using `optimum-cli` : [source,bash] ---- @@ -54,7 +54,7 @@ If the model is not explicitly set, `TransformersEmbeddingClient` defaults to ht | Size | 80MB |=== -Following snippet illustrates how to use the `TransformersEmbeddingClient` manually: +The following snippet illustrates how to use the `TransformersEmbeddingClient` manually: [source,java] ---- @@ -80,11 +80,11 @@ List> embeddings = embeddingClient.embed(List.of("Hello world", "Wo ---- -Note that when created manually you have to call the `afterPropertiesSet()` after setting the properties and before using the client. +Note that when created manually, you must call the `afterPropertiesSet()` after setting the properties and before using the client. The first `embed()` call downloads the large ONNX model and caches it on the local file system. Therefore, the first call might take longer than usual. -Use the `#setResourceCacheDirectory()` to set the local folder where the ONNX models as stored. +Use the `#setResourceCacheDirectory()` method to set the local folder where the ONNX models as stored. The default cache folder is `${java.io.tmpdir}/spring-ai-onnx-model`. It is more convenient (and preferred) to create the TransformersEmbeddingClient as a `Bean`. @@ -98,9 +98,9 @@ public EmbeddingClient embeddingClient() { } ---- -== Transformers Embedding Spring Boot Starter. +== Transformers Embedding Spring Boot Starter -You can bootstrap and auto-wire the `TransformersEmbeddingClient` with following boot starer: +You can bootstrap and autowire the `TransformersEmbeddingClient` with the following Spring Boot starter: [source,xml] ---- @@ -111,9 +111,9 @@ You can bootstrap and auto-wire the `TransformersEmbeddingClient` with following ---- -and use the `spring.ai.embedding.transformer.*` properties to configure it. +To configure it, use the `spring.ai.embedding.transformer.*` properties. -For example add this to your application.properties to configure with the https://huggingface.co/intfloat/e5-small-v2[intfloat/e5-small-v2] text embedding model: +For example, add this to your _application.properties_ file to configure the client with the https://huggingface.co/intfloat/e5-small-v2[intfloat/e5-small-v2] text embedding model: ---- spring.ai.embedding.transformer.onnx.modelUri=https://huggingface.co/intfloat/e5-small-v2/resolve/main/model.onnx @@ -134,7 +134,7 @@ The complete list of supported properties are: | spring.ai.embedding.transformer.metadataMode | Specifies what parts of the Documents content and metadata will be used for computing the embeddings. | NONE |=== -Note: if you see error like: `Caused by: ai.onnxruntime.OrtException: Supplied array is ragged,..` then you need to enable the tokenizer padding in boot starter's `application.properties`: +NOTE: If you see an error like `Caused by: ai.onnxruntime.OrtException: Supplied array is ragged,..`, you need to also enable the tokenizer padding in `application.properties` as follows: ---- spring.ai.embedding.transformer.tokenizer.options.padding=true diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc index c40358b04..0f7309680 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/etl-pipeline.adoc @@ -1,10 +1,10 @@ = ETL Pipeline -The Extraction, Transformation, and Loading (ETL) framework serves as the backbone of data processing within the Retrieval-Augmented Generation (RAG) use case. +The Extract, Transform, and Load (ETL) framework serves as the backbone of data processing within the Retrieval Augmented Generation (RAG) use case. The ETL pipeline orchestrates the flow from raw data sources to a structured vector store, ensuring data is in the optimal format for retrieval by the AI model. -The RAG use-case is text to augment the capabilities of generative models by retrieving relevant information from a body of data to enhancing the quality and relevance of the generated output. +The RAG use case is text to augment the capabilities of generative models by retrieving relevant information from a body of data to enhance the quality and relevance of the generated output. == API Overview @@ -20,16 +20,20 @@ public interface DocumentReader extends Supplier> { ==== Available Implementations -*JsonReader*: Parses documents in JSON format. +*JsonReader*:: ++ Parses documents in JSON format. -*TextReader*: Processes plain text documents. +*TextReader*:: ++ Processes plain text documents. -*PagePdfDocumentReader*: Uses Apache PdfBox library to parse PDF documents +*PagePdfDocumentReader*:: ++ Uses Apache PdfBox library to parse PDF documents -*ParagraphPdfDocumentReader*: Uses the PDF catalog (e.g. TOC) information to split the input PDF into text paragraphs and output a single `Document` per paragraph. +*ParagraphPdfDocumentReader*:: ++ Uses the PDF catalog (e.g. TOC) information to split the input PDF into text paragraphs and output a single `Document` per paragraph. -*TikaDocumentReader*: Uses Apache Tika to extract text from a variety of document - * formats, such as PDF, DOC/DOCX, PPT/PPTX, and HTML. For a comprehensive list of supported formats, refer to the https://tika.apache.org/2.9.0/formats.html[Tika documentation]. +*TikaDocumentReader*:: ++ Uses Apache Tika to extract text from a variety of document formats, such as PDF, DOC/DOCX, PPT/PPTX, and HTML. For a comprehensive list of supported formats, refer to the https://tika.apache.org/2.9.0/formats.html[Tika documentation]. === DocumentTransformer diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/output-parser.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/output-parser.adoc index 8c9d759d0..e8a06cffa 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/output-parser.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/output-parser.adoc @@ -54,7 +54,7 @@ The `OutputParser` interface has the following available implementations. * `BeanOutputParser`: Specifies the JSON schema for Java class and uses `DRAFT_2020_12` of the JSON schema specification as OpenAI has indicated this would give the best results. The JSON output of the AI Model is then deserialized to a Java object, aka `JavaBean`. -* MapOutputParser: Similar to BeanOutputParser but the JSON payload is deserialized into a `java.util.Map instance. +* `MapOutputParser`: Similar to `BeanOutputParser` but the JSON payload is deserialized into a `java.util.Map` instance. * `ListOutputParser`: Specifies the output to be a comma delimited list. @@ -66,7 +66,7 @@ There has been considerable effort in recent OpenAI models to improve the model' You can run a fully working example that demonstrates the use of `BeanOutputParser` as part of the https://github.com/Azure-Samples/spring-ai-azure-workshop[Spring AI Azure Workshop]. Part of this workshop code is reproduced below. -The use case for the example is to as the AI Model to generate the filmography for an actor. +The use case for the example is to use the AI Model to generate the filmography for an actor. The User prompt used is 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 7e7718ab0..ab4f19d58 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 @@ -6,8 +6,8 @@ The design and phrasing of these prompts significantly influence the model's res At the lowest level of interaction with AI models in Spring AI, handling prompts in Spring AI is somewhat similar to managing the "View" in Spring MVC. This involves creating extensive text with placeholders for dynamic content. -These placeholders are then replaced based on user requests or other code in application. -Another analogy is with SQL statement that contain placeholders for certain expressions. +These placeholders are then replaced based on user requests or other code in the application. +Another analogy is a SQL statement that contain placeholders for certain expressions. As Spring AI evolves, it will introduce higher levels of abstraction for interacting with AI models. The foundational classes described in this section can be likened to JDBC in terms of their role and functionality. @@ -16,7 +16,7 @@ Building upon this, Spring AI can provide helper classes similar to `JdbcTemplat The structure of prompts has evolved over time within the AI field. Initially, prompts were simple strings. -Over time, they have evolved to include placeholders for specific inputs, like "USER:", which the AI model recognizes. +Over time, they grew to include placeholders for specific inputs, like "USER:", which the AI model recognizes. OpenAI have introduced even more structure to prompts by categorizing multiple message strings into distinct roles before they are processed by the AI model. @@ -24,7 +24,7 @@ OpenAI have introduced even more structure to prompts by categorizing multiple m === Prompt -It is common to use `ChatClient`s `generate` method which takes a `Prompt` instance and returns an `AiResponse`. +It is common to use the `generate` method of `ChatClient` that takes a `Prompt` instance and returns an `AiResponse`. The Prompt class functions as a container for an organized series of Message objects, with each one forming a segment of the overall prompt. Every Message embodies a unique role within the prompt, differing in its content and intent. @@ -155,7 +155,7 @@ public interface PromptTemplateStringActions { } ``` -The method `String render()` renders a prompt template into a final string format without external input, suitable for templates without placeholders or dynamic content. +The method `String render()`: Renders a prompt template into a final string format without external input, suitable for templates without placeholders or dynamic content. The method `String render(Map model)`: Enhances rendering functionality to include dynamic content. It uses a Map where map keys are placeholder names in the prompt template, and values are the dynamic content to be inserted. @@ -267,15 +267,15 @@ For example, a significant study demonstrated that starting a prompt with "Take This highlights the impact that well-chosen language can have on generative AI systems' performance. Grasping the most effective use of prompts, particularly with the rapid advancement of AI technologies, is a continuous challenge. -You should recognize the importance of prompt engineering and consider using insights from the community and research to improve their prompt creation strategies. +You should recognize the importance of prompt engineering and consider using insights from the community and research to improve prompt creation strategies. === Creating effective prompts When developing prompts, it's important to integrate several key components to ensure clarity and effectiveness: -* *Instructions*: Offer clear and direct instructions to the AI, similar to how you would communicate with a person. This clarity is essential for helping the AI understand what is expected. +* *Instructions*: Offer clear and direct instructions to the AI, similar to how you would communicate with a person. This clarity is essential for helping the AI 'understand' what is expected. -* *External Context*: nclude relevant background information or specific guidance for the AI's response when necessary. This 'external context' frames the prompt and aids the AI in grasping the overall scenario. +* *External Context*: Include relevant background information or specific guidance for the AI's response when necessary. This 'external context' frames the prompt and aids the AI in grasping the overall scenario. * *User Input*: This is the straightforward part - the user's direct request or question forming the core of the prompt. @@ -285,7 +285,7 @@ Providing the AI with examples of the anticipated question and answer format can This practice helps the AI 'understand' the structure and intent of your query, leading to more precise and relevant responses. While this documentation does not delve deeply into these techniques, they provide a starting point for further exploration in AI prompt engineering. -Here is a list of resources for further investigation +Following is a list of resources for further investigation. == Simple Techniques diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs.adoc index 19327888c..faffd8914 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs.adoc @@ -16,7 +16,7 @@ This technique is known as xref:concepts.adoc#concept-rag[Retrieval Augmented Ge The following sections describe the Spring AI interface for using multiple vector database implementations and some high-level sample usage. -The last section attempts to demystify the underlying approach of similarity searching in vector databases. +The last section is intended to demystify the underlying approach of similarity searching in vector databases. == API Overview This section serves as a guide to the `VectorStore` interface and its associated classes within the Spring AI framework. @@ -87,21 +87,21 @@ country == 'UK' && year >= 2020 && isActive == true. These are the available implementations of the `VectorStore` interface: -* Azure Vector Search [`AzureVectorStore`] the https://learn.microsoft.com/en-us/azure/search/vector-search-overview[Azure] vector store -* Chroma [`ChromaVectorStore`]: https://www.trychroma.com/[Chroma] vector store. +* Azure Vector Search [`AzureVectorStore`]: The https://learn.microsoft.com/en-us/azure/search/vector-search-overview[Azure] vector store +* Chroma [`ChromaVectorStore`]: The https://www.trychroma.com/[Chroma] vector store * Milvus [`MilvusVectorStore`]: The https://milvus.io/[Milvus] vector store * Neo4j [`Neo4jVectorStore`]: The https://neo4j.com/[Neo4j] vector store -* PgVector [`PgVectorStore`]: The https://github.com/pgvector/pgvector[PostgreSQL/PGVector] vector store. -* Pinecone: https://www.pinecone.io/[PineCone] vector store. +* PgVector [`PgVectorStore`]: The https://github.com/pgvector/pgvector[PostgreSQL/PGVector] vector store +* Pinecone: https://www.pinecone.io/[PineCone] vector store * Redis [`RedisVectorStore`]: The https://redis.io/[Redis] vector store -* Simple Vector Store [`SimpleVectorStore`]: A simple implementation of persistent vector storage, good for educational purposes. +* Simple Vector Store [`SimpleVectorStore`]: A simple implementation of persistent vector storage, good for educational purposes * Weaviate [`WeaviateVectorStore`] The https://weaviate.io/[Weaviate] vector store More implementations may be supported in future releases. If you have a vector database that needs to be supported by Spring AI, open an issue on GitHub or, even better, submit a pull request with an implementation. -Information on each of the Vector Store implementations can be found in the subsections of this chapter. +Information on each of the `VectorStore` implementations can be found in the subsections of this chapter. == Example Usage diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure.adoc index 510210deb..3bbeac3d3 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure.adoc @@ -1,6 +1,6 @@ = Azure AI Service -This section will walk you through setting up the AzureVectorStore to store document embeddings and perform similarity searches using the Azure AI Search Service. +This section will walk you through setting up the `AzureVectorStore` to store document embeddings and perform similarity searches using the Azure AI Search Service. link:https://azure.microsoft.com/en-us/products/ai-services/cognitive-search[Azure AI Search] is a versatile cloud-hosted cloud information retrieval system that is part of Microsoft's larger AI platform. Among other features, it allows users to query information using vector-based storage and retrieval. @@ -12,7 +12,7 @@ link:https://azure.microsoft.com/en-us/products/ai-services/cognitive-search[Azu == Configuration -On startup, the AzureVectorStore will attempt to create a new index within your AI Search service instance. Alternatively, you can create the index manually as explained in <>. +On startup, the AzureVectorStore will attempt to create a new index within your AI Search service instance. Alternatively, you can create the index manually. To set up an AzureVectorStore, you will need the settings retrieved from the prerequisites above along with your index name: @@ -32,7 +32,7 @@ export OPENAI_API_KEY= (Optional) [NOTE] ==== -You can replace Azure Open AI implementation with any valid OpenAI implementation that supports the Embeddings interface. For example, you could use Spring AI's Open AI or TransformersEmbedding implementations for embeddings instead of the Azure implementation. +You can replace Azure Open AI implementation with any valid OpenAI implementation that supports the Embeddings interface. For example, you could use Spring AI's Open AI or `TransformersEmbedding` implementations for embeddings instead of the Azure implementation. ==== == Dependencies @@ -41,7 +41,7 @@ Add these dependencies to your project: 1. Select an Embeddings interface implementation. You can choose between: -* or OpenAI Embedding: +* OpenAI Embedding: [source,xml] ---- @@ -189,7 +189,7 @@ The portable filter expressions get automatically converted into the proprietary country in ['UK', 'NL'] && year >= 2020 ---- -is converted into Azure OData link:https://learn.microsoft.com/en-us/azure/search/search-query-odata-filter[filter expression]: +is converted into the following Azure OData link:https://learn.microsoft.com/en-us/azure/search/search-query-odata-filter[filter expression]: [source,graphql] ---- diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/concepts.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/concepts.adoc index 558cceb36..71b477550 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/concepts.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/concepts.adoc @@ -42,10 +42,10 @@ The following table categorizes several models based on their input and output t |=== The initial focus of Spring AI is on models that process language input and provide language output, initially OpenAI + Azure OpenAI. -The last row in the previous table, which accepts text as input and output numbers, is more commonly known as embedding text and represents the internal data structures used in an AI model. +The last row in the previous table, which accepts text as input and outputs numbers, is more commonly known as embedding text and represents the internal data structures used in an AI model. Spring AI has support for embeddings to support more advanced use cases. -What sets models like GPT apart is their pre-trained nature, as indicated by the "P" in GPT—Chat Generative Pre-Trained Transformer. +What sets models like GPT apart is their pre-trained nature, as indicated by the "P" in GPT—Chat Generative Pre-trained Transformer. This pre-training feature transforms AI into a general developer tool that does not require an extensive machine learning or model training background. == Prompts @@ -78,7 +78,7 @@ We do not yet fully understand how to make the most effective use of previous it Creating effective prompts involves establishing the context of the request and substituting parts of the request with values specific to the user's input. This process uses traditional text-based template engines for prompt creation and management. -Spring AI employs the OSS library, StringTemplate, for this purpose. +Spring AI employs the OSS library https://www.stringtemplate.org/[StringTemplate] for this purpose. For instance, consider the simple prompt template: @@ -100,13 +100,13 @@ This transformation from text to numbers and back is a key element in how AI int As a Java developer exploring AI, it's not necessary to comprehend the intricate mathematical theories or the specific implementations behind these vector representations. A basic understanding of their role and function within AI systems suffices, particularly when you're integrating AI functionalities into your applications. -Embeddings are particularly relevant in practical applications like the retrieval-augmented generation pattern. +Embeddings are particularly relevant in practical applications like the Retrieval Augmented Generation (RAG) pattern. They enable the representation of data as points in a semantic space, which is akin to the 2-D space of Euclidean geometry, but in higher dimensions. This means just like how points on a plane in Euclidean geometry can be close or far based on their coordinates, in a semantic space, the proximity of points reflects the similarity in meaning. -So, sentences about similar topics are positioned closer in this multi-dimensional space, much like points lying close to each other on a graph. +Sentences about similar topics are positioned closer in this multi-dimensional space, much like points lying close to each other on a graph. This proximity aids in tasks like text classification, semantic search, and even product recommendations, as it allows the AI to discern and group related concepts based on their 'location' in this expanded semantic landscape. -You can think of this semantic space as a vector, +You can think of this semantic space as a vector. == Tokens @@ -154,9 +154,9 @@ Two techniques exist for customizing the AI model to incorporate your data: However, it is a challenging process for machine learning experts and extremely resource-intensive for models like GPT due to their size. Additionally, some models might not offer this option. * Prompt Stuffing: A more practical alternative involves embedding your data within the prompt provided to the model. Given a model's token limits, techniques are required to present relevant data within the model's context window. -This approach is colloquially referred to as "'stuffing the prompt.'" +This approach is colloquially referred to as "`stuffing the prompt.`" -The Spring AI library helps you implement solutions based on the "'stuffing the prompt'" technique otherwise known as Retrieval Augmented Generation (RAG). +The Spring AI library helps you implement solutions based on the "`stuffing the prompt`" technique otherwise known as Retrieval Augmented Generation (RAG). [[concept-rag]] == Retrieval Augmented Generation @@ -167,26 +167,26 @@ The approach involves a batch processing style programming model, where the job At a high level, this is an ETL (Extract, Transform and Load) pipeline. The vector database is used in the retrieval part of RAG technique. -As part of loading the unstructured data into the vector database, one of the most important transformations is to split up the original document into smaller pieces. -The procedure of splitting up the original document into smaller pieces has two important steps: +As part of loading the unstructured data into the vector database, one of the most important transformations is to split the original document into smaller pieces. +The procedure of splitting the original document into smaller pieces has two important steps: -. Split up the document into parts while preserving the semantic boundaries of the content. +. Split the document into parts while preserving the semantic boundaries of the content. For example, for a document with paragraphs and tables, one should avoid splitting the document in the middle of a paragraph or table. For code, avoid splitting the code in the middle of a method's implementation. -. Split up the document's parts further into parts whose size is a small percentage of the AI Model's token limit. +. Split the document's parts further into parts whose size is a small percentage of the AI Model's token limit. The next phase in RAG is processing user input. -When a user's question is to be answered by an AI model, the question and all the "'similar'" document pieces are placed into the prompt that is sent to the AI model. -This is the reason to use a vector database. It is very good at finding 'similar' content. +When a user's question is to be answered by an AI model, the question and all the "`similar`" document pieces are placed into the prompt that is sent to the AI model. +This is the reason to use a vector database. It is very good at finding similar content. There are several concepts that are used in implementing RAG. The concepts map onto classes in Spring AI: * `DocumentReader`: A Java functional interface that is responsible for loading a `List` from a data source. Common data sources are PDF, Markdown, and JSON. * `Document`: A text-based representation of your data source that also contains metadata to describe the contents. -* `DocumentTransformer`: Responsible for processing the data in various ways (for example, splitting up documents into smaller pieces or adding additional metadata to the `Document`.) +* `DocumentTransformer`: Responsible for processing the data in various ways (for example, splitting documents into smaller pieces or adding additional metadata to the `Document`). * `DocumentWriter`: Lets you persist the Documents into a database (most commonly in the AI stack, a vector database). -* `Embedding`: A representation of your data as a `List` that is used by the vector database to compute the "'similarity'" of a user's query to relevant documents. +* `Embedding`: A representation of your data as a `List` that is used by the vector database to compute the "`similarity`" of a user's query to relevant documents. == Evaluating AI responses diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc index fc3f956a6..3607d2bf3 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/getting-started.adoc @@ -7,7 +7,7 @@ This section offers jumping off points for how to get started using Spring AI. The Spring AI project provides artifacts in the Spring Milestone and Snapshot repositories. -You need to add configuration to add a reference to the Spring Milestone or Snapshot repository in your build file. +You need to add references to the Spring Milestone and/or Snapshot repositories in your build file. For Maven, add the following repository definitions as needed: @@ -49,11 +49,10 @@ repositories { == Chat Models * xref:api/clients/openai.adoc#_getting_started[OpenAI] -* xref:api/clients/azure-openai.adoc#_gettting_started[Azure OpenAI] +* xref:api/clients/azure-openai.adoc#_getting_started[Azure OpenAI] * xref:api/clients/huggingface.adoc#_getting_started[HuggingFace] -* xref:api/clients/bedrock.adoc +* xref:api/clients/bedrock.adoc#_getting_started[Bedrock] * xref:api/clients/ollama.adoc#_getting_started[Ollama] -* == Embedding Models diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/index.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/index.adoc index a22546a82..da94beaed 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/index.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/index.adoc @@ -14,8 +14,7 @@ In addition to these core abstractions, Spring AI aims to provide higher-level f As the complexity of the use cases increases, the Spring AI project will integrate with other projects in the Spring Ecosystem, such as Spring Integration, Spring Batch, and Spring Data. To simplify setup, Spring Boot starters are available to help set up essential dependencies and classes. -There is also a collection of sample applications to help you explore the project's features. -Lastly, the new Spring CLI project also enables you to get started quickly by using the `spring boot new ai` command for new projects or `spring boot add ai` for adding AI capabilities to your existing application. +There is also a collection of sample applications to help you explore the project's features. Lastly, the new Spring CLI project also enables you to get started quickly by using the `spring boot new ai` command for new projects or `spring boot add ai` for adding AI capabilities to your existing application. The xref:concepts.adoc[next section] provides a high-level overview of AI concepts and their representation in Spring AI. The xref:getting-started.adoc[Getting Started] section shows you how to create your first AI application.