Clarify postgresml-embeddings.adoc
This commit is contained in:
Christian Tzolov
@@ -6,14 +6,87 @@ Embeddings are a numeric representation of text.
|
||||
They are used to represent words and sentences as vectors, an array of numbers.
|
||||
Embeddings can be used to find similar pieces of text, by comparing the similarity of the numeric vectors using a distance measure, or they can be used as input features for other machine learning models, since most algorithms can't use text directly.
|
||||
|
||||
Many pretrained LLMs can be used to generate embeddings from text within PostgresML.
|
||||
Many pre-trained LLMs can be used to generate embeddings from text within PostgresML.
|
||||
You can browse all the https://huggingface.co/models?library=sentence-transformers[models] available to find the best solution on Hugging Face.
|
||||
|
||||
== Getting Started
|
||||
== Auto-configuration
|
||||
|
||||
=== Configure the PostgresML Embeddings Client Manually
|
||||
Spring AI provides Spring Boot auto-configuration for the Azure PostgresML Embedding Client.
|
||||
To enable it add the following dependency to your project's Maven `pom.xml` file:
|
||||
|
||||
[source, xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-postgresml-spring-boot-starter</artifactId>
|
||||
<version>0.8.0-SNAPSHOT</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
or to your Gradle `build.gradle` build file.
|
||||
|
||||
[source,groovy]
|
||||
----
|
||||
dependencies {
|
||||
implementation 'org.springframework.ai:spring-ai-postgresml-spring-boot-starter:0.8.0-SNAPSHOT'
|
||||
}
|
||||
----
|
||||
|
||||
NOTE: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file.
|
||||
|
||||
Use the `spring.ai.postgresml.embedding.options.*` properties to configure your `PostgresMlEmbeddingClient`. links
|
||||
|
||||
=== Embedding Properties
|
||||
|
||||
The prefix `spring.ai.postgres.embedding` is property prefix that configures the `EmbeddingClient` implementation for PostgresML embeddings.
|
||||
|
||||
[cols="3,5,1"]
|
||||
|====
|
||||
| Property | Description | Default
|
||||
| spring.ai.postgres.embedding.options.transformer | The Huggingface transformer model to use for the embedding. | distilbert-base-uncased
|
||||
| spring.ai.postgres.embedding.options.kwargs | Additional transformer specific options. | empty map
|
||||
| spring.ai.postgres.embedding.options.vectorType | PostgresML vector type to use for the embedding. Two options are supported: `PG_ARRAY` and `PG_VECTOR`. | PG_ARRAY
|
||||
| spring.ai.postgres.embedding.options.metadataMode | Document metadata aggregation mode | EMBED
|
||||
|====
|
||||
|
||||
=== Sample Controller
|
||||
|
||||
This will create a `EmbeddingClient` implementation that you can inject into your class.
|
||||
Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation.
|
||||
|
||||
[source,application.properties]
|
||||
----
|
||||
spring.ai.postgres.embedding.options.transformer=distilbert-base-uncased
|
||||
spring.ai.postgres.embedding.options.vectorType=PG_ARRAY
|
||||
spring.ai.postgres.embedding.options.metadataMode=EMBED
|
||||
spring.ai.postgres.embedding.options.kwargs.device=cpu
|
||||
----
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@RestController
|
||||
public class EmbeddingController {
|
||||
|
||||
private final EmbeddingClient embeddingClient;
|
||||
|
||||
@Autowired
|
||||
public EmbeddingController(EmbeddingClient embeddingClient) {
|
||||
this.embeddingClient = embeddingClient;
|
||||
}
|
||||
|
||||
@GetMapping("/ai/embedding")
|
||||
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
|
||||
EmbeddingResponse embeddingResponse = this.embeddingClient.embedForResponse(List.of(message));
|
||||
return Map.of("embedding", embeddingResponse);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
== Manual configuration
|
||||
|
||||
Instead of using the Spring Boot auto-configuration, you can create the `PostgresMlEmbeddingClient` manually.
|
||||
For this add the `spring-ai-postgresml` dependency to your project's Maven `pom.xml` file:
|
||||
|
||||
Add the `spring-ai-postgresml` dependency to your project's Maven `pom.xml` file:
|
||||
[source, xml]
|
||||
----
|
||||
<dependency>
|
||||
@@ -60,18 +133,14 @@ Then you don’t have to call the `afterPropertiesSet()` manually:
|
||||
----
|
||||
@Bean
|
||||
public EmbeddingClient embeddingClient(JdbcTemplate jdbcTemplate) {
|
||||
|
||||
return new PostgresMlEmbeddingClient(jdbcTemplate,
|
||||
PostgresMlEmbeddingOptions.builder()
|
||||
.withTransformer("distilbert-base-uncased")
|
||||
.withVectorType(VectorType.PG_VECTOR)
|
||||
.withKwargs(Map.of("device", "cpu"))
|
||||
.withMetadataMode(MetadataMode.EMBED)
|
||||
....
|
||||
.build());
|
||||
}
|
||||
----
|
||||
|
||||
==== OpenAiEmbeddingOptions
|
||||
=== EmbeddingOptions
|
||||
|
||||
Use the https://github.com/spring-projects/spring-ai/blob/main/models/spring-ai-openai/src/main/java/org/springframework/ai/postgresml/PostgresMlEmbeddingOptions.java[PostgresMlEmbeddingOptions.java] to configure the `PostgresMlEmbeddingClient` with options, such as the model to use and etc.
|
||||
|
||||
@@ -94,76 +163,4 @@ EmbeddingResponse embeddingResponse = embeddingClient.call(
|
||||
.build()));
|
||||
----
|
||||
|
||||
=== PostgresMlEmbeddingClient Auto-configuration
|
||||
|
||||
Spring AI provides Spring Boot auto-configuration for the Azure PostgresML Embedding Client.
|
||||
To enable it add the following dependency to your project's Maven `pom.xml` file:
|
||||
|
||||
[source, xml]
|
||||
----
|
||||
<dependency>
|
||||
<groupId>org.springframework.ai</groupId>
|
||||
<artifactId>spring-ai-postgresml-spring-boot-starter</artifactId>
|
||||
<version>0.8.0-SNAPSHOT</version>
|
||||
</dependency>
|
||||
----
|
||||
|
||||
or to your Gradle `build.gradle` build file.
|
||||
|
||||
[source,groovy]
|
||||
----
|
||||
dependencies {
|
||||
implementation 'org.springframework.ai:spring-ai-postgresml-spring-boot-starter:0.8.0-SNAPSHOT'
|
||||
}
|
||||
----
|
||||
|
||||
NOTE: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file.
|
||||
|
||||
Use the `spring.ai.postgresml.embedding.options.*` properties to configure your `PostgresMlEmbeddingClient`. links
|
||||
|
||||
==== Sample Embedding Controller
|
||||
|
||||
This will create a `EmbeddingClient` implementation that you can inject into your class.
|
||||
Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation.
|
||||
|
||||
[source,application.properties]
|
||||
----
|
||||
spring.ai.postgres.embedding.options.transformer=distilbert-base-uncased
|
||||
spring.ai.postgres.embedding.options.vectorType=PG_ARRAY
|
||||
spring.ai.postgres.embedding.options.metadataMode=EMBED
|
||||
spring.ai.postgres.embedding.options.kwargs.device=cpu
|
||||
----
|
||||
|
||||
[source,java]
|
||||
----
|
||||
@RestController
|
||||
public class EmbeddingController {
|
||||
|
||||
private final EmbeddingClient embeddingClient;
|
||||
|
||||
@Autowired
|
||||
public EmbeddingController(EmbeddingClient embeddingClient) {
|
||||
this.embeddingClient = embeddingClient;
|
||||
}
|
||||
|
||||
@GetMapping("/ai/embedding")
|
||||
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
|
||||
EmbeddingResponse embeddingResponse = this.embeddingClient.embedForResponse(List.of(message));
|
||||
return Map.of("embedding", embeddingResponse);
|
||||
}
|
||||
}
|
||||
----
|
||||
|
||||
== PostgresML Embedding Properties
|
||||
|
||||
The prefix `spring.ai.postgres.embedding` is property prefix that configures the `EmbeddingClient` implementation for PostgresML embeddings.
|
||||
|
||||
[cols="3,5,1"]
|
||||
|====
|
||||
| Property | Description | Default
|
||||
| spring.ai.postgres.embedding.options.transformer | The Huggingface transformer model to use for the embedding. | distilbert-base-uncased
|
||||
| spring.ai.postgres.embedding.options.kwargs | Additional transformer specific options. | empty map
|
||||
| spring.ai.postgres.embedding.options.vectorType | PostgresML vector type to use for the embedding. Two options are supported: `PG_ARRAY` and `PG_VECTOR`. | PG_ARRAY
|
||||
| spring.ai.postgres.embedding.options.metadataMode | Document metadata aggregation mode | EMBED
|
||||
|====
|
||||
|
||||
|
||||
Reference in New Issue
Block a user