From 6e4057597757ed99d1ba2379291b4a0e894fb3cc Mon Sep 17 00:00:00 2001 From: Thomas Vitale Date: Wed, 1 May 2024 22:11:59 +0200 Subject: [PATCH] Docs: Fix typos and add missing pieces Signed-off-by: Thomas Vitale --- .../modules/ROOT/pages/api/generic-model.adoc | 5 ++-- .../pages/api/image/stabilityai-image.adoc | 2 +- .../antora/modules/ROOT/pages/api/index.adoc | 6 ++--- .../antora/modules/ROOT/pages/api/prompt.adoc | 4 +-- .../ROOT/pages/api/testcontainers.adoc | 25 ++++++++++++++++++- .../modules/ROOT/pages/api/vectordbs.adoc | 8 +++--- .../api/vectordbs/understand-vectordbs.adoc | 2 +- .../antora/modules/ROOT/pages/concepts.adoc | 14 ++++++++--- .../modules/ROOT/pages/getting-started.adoc | 4 ++- .../main/antora/modules/ROOT/pages/index.adoc | 10 ++++---- 10 files changed, 57 insertions(+), 23 deletions(-) diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/generic-model.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/generic-model.adoc index 197fccb99..6b30f90bc 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/generic-model.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/generic-model.adoc @@ -31,7 +31,7 @@ public interface ModelClient, TRes extends ModelRes == StreamingModelClient -The StreamingModelClient interface provides a generic API for invoking an AI models with streaming response. It abstracts the process of sending requests and receiving a streaming responses. The interface uses Java generics to accommodate different types of requests and responses, enhancing flexibility and adaptability across different AI model implementations. +The StreamingModelClient interface provides a generic API for invoking an AI model with streaming response. It abstracts the process of sending requests and receiving a streaming response. The interface uses Java generics to accommodate different types of requests and responses, enhancing flexibility and adaptability across different AI model implementations. [source,java] ---- @@ -113,7 +113,8 @@ public interface ModelResponse> { == ModelResult - This interface provides methods to access the main output of the AI model and the metadata associated with this result. It is designed to offer a standardized and comprehensive way to handle and interpret the outputs generated by AI models. + +This interface provides methods to access the main output of the AI model and the metadata associated with this result. It is designed to offer a standardized and comprehensive way to handle and interpret the outputs generated by AI models. [source,java] ---- diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/stabilityai-image.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/stabilityai-image.adoc index 6cb28510e..b526b5405 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/stabilityai-image.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/image/stabilityai-image.adoc @@ -7,7 +7,7 @@ Spring AI supports Stability AI's https://platform.stability.ai/docs/api-referen You will need to create an API key with Stability AI to access their AI models, follow their https://platform.stability.ai/docs/getting-started/authentication[Getting Started documentation]. The Spring AI project defines a configuration property named `spring.ai.stabilityai.api-key` that you should set to the value of the `API Key` obtained from Stability AI. -Exporting an environment variable in one way to set that configuration property. +Exporting an environment variable is one way to set that configuration property. [source,shell] ---- diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/index.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/index.adoc index 34173971e..1d14d3589 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/index.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/index.adoc @@ -6,9 +6,9 @@ The Spring AI API covers a wide range of functionalities. Each major feature is detailed in its own dedicated section. To provide an overview, the following key functionalities are available: -* Portable API across AI providers for Chat, Text to Image, and Embedding models. Both synchronous and stream API options are supported. Dropping down to access model specific features is also supported. We support AI Models from OpenAI, Microsoft, Amazon, Google, Huggingface and more. -* Portable API across Vector Store providers, including a novel SQL-like metadata filter API that is also portable. Support for 8 vector databases are available. -* Function calling. Spring AI makes it easy to have the AI model invoke your POJO java.util.Function object. +* Portable API across AI providers for Chat, Text to Image, Audio Transcription, Text to Speech, and Embedding models. Both synchronous and stream API options are supported. Dropping down to access model specific features is also supported. We support AI Models from OpenAI, Microsoft, Amazon, Google, Huggingface and more. +* Portable API across Vector Store providers, including a novel SQL-like metadata filter API that is also portable. Support for 14 vector databases are available. +* Function calling. Spring AI makes it easy to have the AI model invoke your POJO `java.util.Function` object. * Spring Boot Auto Configuration and Starters for AI Models and Vector Stores. * ETL framework for Data Engineering. This provides the basis of loading data into a vector database, helping implement the Retrieval Augmented Generation pattern that enables you to bring your data to the AI model to incorporate into its response. 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 054d829bd..3f1052981 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 @@ -24,7 +24,7 @@ OpenAI have introduced even more structure to prompts by categorizing multiple m === Prompt -It is common to use the `generate` method of `ChatClient` that takes a `Prompt` instance and returns an `ChatResponse`. +It is common to use the `call` method of `ChatClient` that takes a `Prompt` instance and returns an `ChatResponse`. 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. @@ -126,7 +126,7 @@ public enum MessageType { === PromptTemplate A key component for prompt templating in Spring AI is the `PromptTemplate` class. -This class uses the StringTemplate engine, developed by Terence Parr, for constructing and managing prompts. +This class uses the OSS https://www.stringtemplate.org/[StringTemplate] engine, developed by Terence Parr, for constructing and managing prompts. The `PromptTemplate` class is designed to facilitate the creation of structured prompts that are then sent to the AI model for processing ```java diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/testcontainers.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/testcontainers.adoc index f43fa75d8..8a33c21af 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/testcontainers.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/testcontainers.adoc @@ -1,9 +1,32 @@ [[testcontainers]] = Testcontainers +Spring AI provides Spring Boot auto-configuration for establishing a connection to a model service +or vector store running via Testcontainers. To enable it, add the following dependency +to your project's Maven `pom.xml` file: + +[source,xml] +---- + + org.springframework.ai + spring-ai-spring-boot-testcontainers + +---- + +or to your Gradle `build.gradle` build file. + +[source,groovy] +---- +dependencies { + implementation 'org.springframework.ai:spring-ai-spring-boot-testcontainers' +} +---- + +TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file. + == Service Connections -The following service connection factories are provided in the spring-ai-spring-boot-testcontainers jar: +The following service connection factories are provided in the `spring-ai-spring-boot-testcontainers` module: [cols="|,|"] |==== 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 d16a21125..e7725d6e6 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 @@ -87,9 +87,10 @@ Find more information on the `Filter.Expression` in the <> sec These are the available implementations of the `VectorStore` interface: -* xref:api/vectordbs/azure.adoc[ Azure Vector Search] - The https://learn.microsoft.com/en-us/azure/search/vector-search-overview[Azure] vector store. -* xref:api/vectordbs/apache-cassandra.adoc[Apache Cassandra] - The https://cassandra.apache.org/doc/latest/cassandra/vector-search/overview.html[Apache Cassandra] +* xref:api/vectordbs/azure.adoc[Azure Vector Search] - The https://learn.microsoft.com/en-us/azure/search/vector-search-overview[Azure] vector store. +* xref:api/vectordbs/apache-cassandra.adoc[Apache Cassandra] - The https://cassandra.apache.org/doc/latest/cassandra/vector-search/overview.html[Apache Cassandra] vector store. * xref:api/vectordbs/chroma.adoc[Chroma Vector Store] - The https://www.trychroma.com/[Chroma] vector store. +* xref:api/vectordbs/elasticsearch.adoc[Elasticsearch Vector Store] - The https://www.elastic.co/[Elasticsearch] vector store. * xref:api/vectordbs/gemfire.adoc[GemFire Vector Store] - The https://tanzu.vmware.com/content/blog/vmware-gemfire-vector-database-extension[GemFire] vector store. * xref:api/vectordbs/milvus.adoc[Milvus Vector Store] - The https://milvus.io/[Milvus] vector store. * xref:api/vectordbs/mongodb.adoc[MongoDB Atlas Vector Store] - The https://www.mongodb.com/atlas/database[MongoDB Atlas] vector store. @@ -100,7 +101,6 @@ These are the available implementations of the `VectorStore` interface: * xref:api/vectordbs/redis.adoc[Redis Vector Store] - The https://redis.io/[Redis] vector store. * xref:api/vectordbs/hana.adoc[SAP Hana Vector Store] - The https://news.sap.com/2024/04/sap-hana-cloud-vector-engine-ai-with-business-context/[SAP HANA] vector store. * xref:api/vectordbs/weaviate.adoc[Weaviate Vector Store] - The https://weaviate.io/[Weaviate] vector store. -vector store. * link:https://github.com/spring-projects/spring-ai/blob/main/spring-ai-core/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java[SimpleVectorStore] - A simple implementation of persistent vector storage, good for educational purposes. More implementations may be supported in future releases. @@ -113,7 +113,7 @@ Information on each of the `VectorStore` implementations can be found in the sub To compute the embeddings for a vector database, you need to pick an embedding model that matches the higher-level AI model being used. -For example, with OpenAI's ChatGPT, we use the `OpenAiEmbeddingClient` and a model name of `text-embedding-ada-002`. +For example, with OpenAI's ChatGPT, we use the `OpenAiEmbeddingClient` and a model named `text-embedding-ada-002`. The Spring Boot starter's auto-configuration for OpenAI makes an implementation of `EmbeddingClient` available in the Spring application context for dependency injection. diff --git a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/understand-vectordbs.adoc b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/understand-vectordbs.adoc index a5fea74be..faf5fab62 100644 --- a/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/understand-vectordbs.adoc +++ b/spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/understand-vectordbs.adoc @@ -91,5 +91,5 @@ It expands the two-dimensional definitions of Magnitude and Dot Product given pr stem:[similarity(vec{A},vec{B}) = \cos(\theta) = \frac{ \sum_{i=1}^{n} {A_i B_i} }{ \sqrt{\sum_{i=1}^{n}{A_i^2} \cdot \sum_{i=1}^{n}{B_i^2}}] **** -This is the key formula used in the simple implementation of a vector store and can be found in the `InMemoryVectorStore` implementation. +This is the key formula used in the simple implementation of a vector store and can be found in the `SimpleVectorStore` implementation. 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 79cd82f04..721ce17ea 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 @@ -36,12 +36,20 @@ The following table categorizes several models based on their input and output t |Image |Midjourney, Stable Diffusion, RunwayML +|Language +|Audio +|OpenAI, Azure OpenAI + +|Audio +|Language +|OpenAI, Azure OpenAI + |Text |Numbers |Many (AKA embeddings) |=== -The initial focus of Spring AI is on models that process language input and provide language output, initially OpenAI + Azure OpenAI. +Spring AI currently supports models that process input and output as language, image, and audio. 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. @@ -115,7 +123,7 @@ On input, models convert words to tokens. On output, they convert tokens back to In English, one token roughly corresponds to 75% of a word. For reference, Shakespeare's complete works, totaling around 900,000 words, translates to approximately 1.2 million tokens. -Perhaps more important is that Tokens = *`$`*. +Perhaps more important is that Tokens = Money. In the context of hosted AI models, your charges are determined by the number of tokens used. Both input and output contribute to the overall token count. @@ -195,7 +203,7 @@ The concepts map onto classes in Spring AI: Large Language Models (LLMs) are frozen after training, leading to stale knowledge and they are unable to access or modify external data. The `Function Calling` mechanism addresses these shortcomings. -It allows you register custom, user, functions that connect the large language models to the APIs of external systems. +It allows you to register your own functions to connect the large language models to the APIs of external systems. These systems can provide LLMs with real-time data and perform data processing actions on their behalf. Spring AI greatly simplifies code you need to write to support function invocation. 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 e2f04a079..d140e3c56 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 @@ -26,7 +26,9 @@ spring boot new --from ai --name myai ``` . Consult the generated `README.md` file for guidance on obtaining an OpenAI API Key and running your first AI application. -To add the same simple AI application to an *existing* project, execute: +NOTE: Currently, the Spring CLI only supports Maven projects. + +To add the same simple AI application to an *existing* Maven project, execute: ```shell spring boot add ai 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 a6761e612..9b78c9904 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 @@ -12,14 +12,14 @@ These abstractions have multiple implementations, enabling easy component swappi Spring AI provides the following features: * Support for all major Model providers such as OpenAI, Microsoft, Amazon, Google, and Huggingface. -* Supported Model types are Chat and Text to Image with more on the way. -* Portable API across AI providers for Chat and for Embedding models. Both synchronous and stream API options are supported. Dropping down to access model specific features is also supported. +* Supported Model types are Chat, Text to Image, Audio Transcription, Text to Speech, and more on the way. +* Portable API across AI providers for all models. Both synchronous and stream API options are supported. Dropping down to access model specific features is also supported. * Mapping of AI Model output to POJOs. -* Support for all major Vector Database providers such as Apache Cassandra, Azure Vector Search, Chroma, Milvus, Neo4j, PostgreSQL/PGVector, PineCone, Qdrant, Redis, and Weaviate +* Support for all major Vector Database providers such as Apache Cassandra, Azure Vector Search, Chroma, Milvus, Neo4j, PostgreSQL/PGVector, PineCone, Qdrant, Redis, and Weaviate. * Portable API across Vector Store providers, including a novel SQL-like metadata filter API that is also portable. -* Function calling +* Function calling. * Spring Boot Auto Configuration and Starters for AI Models and Vector Stores. -* ETL framework for Data Engineering +* ETL framework for Data Engineering. This feature set lets you implement common use cases such as "`Q&A over your documentation`" or "`Chat with your documentation.`"