Skip to content

Commit aff4506

Browse files
tzolovtzolov
committed
Clarify postgresml-embeddings.adoc
1 parent ed6a464 commit aff4506

File tree

1 file changed

+79
-82
lines changed

1 file changed

+79
-82
lines changed

‎spring-ai-docs/src/main/antora/modules/ROOT/pages/api/embeddings/postgresml-embeddings.adoc

Lines changed: 79 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,87 @@ Embeddings are a numeric representation of text.
66
They are used to represent words and sentences as vectors, an array of numbers.
77
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.
88

9-
Many pretrained LLMs can be used to generate embeddings from text within PostgresML.
9+
Many pre-trained LLMs can be used to generate embeddings from text within PostgresML.
1010
You can browse all the https://huggingface.co/models?library=sentence-transformers[models] available to find the best solution on Hugging Face.
1111

12-
== Getting Started
12+
== Auto-configuration
1313

14-
=== Configure the PostgresML Embeddings Client Manually
14+
Spring AI provides Spring Boot auto-configuration for the Azure PostgresML Embedding Client.
15+
To enable it add the following dependency to your project's Maven `pom.xml` file:
16+
17+
[source, xml]
18+
----
19+
<dependency>
20+
<groupId>org.springframework.ai</groupId>
21+
<artifactId>spring-ai-postgresml-spring-boot-starter</artifactId>
22+
<version>0.8.0-SNAPSHOT</version>
23+
</dependency>
24+
----
25+
26+
or to your Gradle `build.gradle` build file.
27+
28+
[source,groovy]
29+
----
30+
dependencies {
31+
implementation 'org.springframework.ai:spring-ai-postgresml-spring-boot-starter:0.8.0-SNAPSHOT'
32+
}
33+
----
34+
35+
NOTE: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file.
36+
37+
Use the `spring.ai.postgresml.embedding.options.*` properties to configure your `PostgresMlEmbeddingClient`. links
38+
39+
=== Embedding Properties
40+
41+
The prefix `spring.ai.postgres.embedding` is property prefix that configures the `EmbeddingClient` implementation for PostgresML embeddings.
42+
43+
[cols="3,5,1"]
44+
|====
45+
| Property | Description | Default
46+
| spring.ai.postgres.embedding.options.transformer | The Huggingface transformer model to use for the embedding. | distilbert-base-uncased
47+
| spring.ai.postgres.embedding.options.kwargs | Additional transformer specific options. | empty map
48+
| 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
49+
| spring.ai.postgres.embedding.options.metadataMode | Document metadata aggregation mode | EMBED
50+
|====
51+
52+
=== Sample Controller
53+
54+
This will create a `EmbeddingClient` implementation that you can inject into your class.
55+
Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation.
56+
57+
[source,application.properties]
58+
----
59+
spring.ai.postgres.embedding.options.transformer=distilbert-base-uncased
60+
spring.ai.postgres.embedding.options.vectorType=PG_ARRAY
61+
spring.ai.postgres.embedding.options.metadataMode=EMBED
62+
spring.ai.postgres.embedding.options.kwargs.device=cpu
63+
----
64+
65+
[source,java]
66+
----
67+
@RestController
68+
public class EmbeddingController {
69+
70+
private final EmbeddingClient embeddingClient;
71+
72+
@Autowired
73+
public EmbeddingController(EmbeddingClient embeddingClient) {
74+
this.embeddingClient = embeddingClient;
75+
}
76+
77+
@GetMapping("/ai/embedding")
78+
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
79+
EmbeddingResponse embeddingResponse = this.embeddingClient.embedForResponse(List.of(message));
80+
return Map.of("embedding", embeddingResponse);
81+
}
82+
}
83+
----
84+
85+
== Manual configuration
86+
87+
Instead of using the Spring Boot auto-configuration, you can create the `PostgresMlEmbeddingClient` manually.
88+
For this add the `spring-ai-postgresml` dependency to your project's Maven `pom.xml` file:
1589

16-
Add the `spring-ai-postgresml` dependency to your project's Maven `pom.xml` file:
1790
[source, xml]
1891
----
1992
<dependency>
@@ -60,18 +133,14 @@ Then you don’t have to call the `afterPropertiesSet()` manually:
60133
----
61134
@Bean
62135
public EmbeddingClient embeddingClient(JdbcTemplate jdbcTemplate) {
63-
64136
return new PostgresMlEmbeddingClient(jdbcTemplate,
65137
PostgresMlEmbeddingOptions.builder()
66-
.withTransformer("distilbert-base-uncased")
67-
.withVectorType(VectorType.PG_VECTOR)
68-
.withKwargs(Map.of("device", "cpu"))
69-
.withMetadataMode(MetadataMode.EMBED)
138+
....
70139
.build());
71140
}
72141
----
73142

74-
==== OpenAiEmbeddingOptions
143+
=== EmbeddingOptions
75144

76145
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.
77146

@@ -94,76 +163,4 @@ EmbeddingResponse embeddingResponse = embeddingClient.call(
94163
.build()));
95164
----
96165

97-
=== PostgresMlEmbeddingClient Auto-configuration
98-
99-
Spring AI provides Spring Boot auto-configuration for the Azure PostgresML Embedding Client.
100-
To enable it add the following dependency to your project's Maven `pom.xml` file:
101-
102-
[source, xml]
103-
----
104-
<dependency>
105-
<groupId>org.springframework.ai</groupId>
106-
<artifactId>spring-ai-postgresml-spring-boot-starter</artifactId>
107-
<version>0.8.0-SNAPSHOT</version>
108-
</dependency>
109-
----
110-
111-
or to your Gradle `build.gradle` build file.
112-
113-
[source,groovy]
114-
----
115-
dependencies {
116-
implementation 'org.springframework.ai:spring-ai-postgresml-spring-boot-starter:0.8.0-SNAPSHOT'
117-
}
118-
----
119-
120-
NOTE: Refer to the xref:getting-started.adoc#_dependency_management[Dependency Management] section to add Milestone and/or Snapshot Repositories to your build file.
121-
122-
Use the `spring.ai.postgresml.embedding.options.*` properties to configure your `PostgresMlEmbeddingClient`. links
123-
124-
==== Sample Embedding Controller
125-
126-
This will create a `EmbeddingClient` implementation that you can inject into your class.
127-
Here is an example of a simple `@Controller` class that uses the `EmbeddingClient` implementation.
128-
129-
[source,application.properties]
130-
----
131-
spring.ai.postgres.embedding.options.transformer=distilbert-base-uncased
132-
spring.ai.postgres.embedding.options.vectorType=PG_ARRAY
133-
spring.ai.postgres.embedding.options.metadataMode=EMBED
134-
spring.ai.postgres.embedding.options.kwargs.device=cpu
135-
----
136-
137-
[source,java]
138-
----
139-
@RestController
140-
public class EmbeddingController {
141-
142-
private final EmbeddingClient embeddingClient;
143-
144-
@Autowired
145-
public EmbeddingController(EmbeddingClient embeddingClient) {
146-
this.embeddingClient = embeddingClient;
147-
}
148-
149-
@GetMapping("/ai/embedding")
150-
public Map embed(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
151-
EmbeddingResponse embeddingResponse = this.embeddingClient.embedForResponse(List.of(message));
152-
return Map.of("embedding", embeddingResponse);
153-
}
154-
}
155-
----
156-
157-
== PostgresML Embedding Properties
158-
159-
The prefix `spring.ai.postgres.embedding` is property prefix that configures the `EmbeddingClient` implementation for PostgresML embeddings.
160-
161-
[cols="3,5,1"]
162-
|====
163-
| Property | Description | Default
164-
| spring.ai.postgres.embedding.options.transformer | The Huggingface transformer model to use for the embedding. | distilbert-base-uncased
165-
| spring.ai.postgres.embedding.options.kwargs | Additional transformer specific options. | empty map
166-
| 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
167-
| spring.ai.postgres.embedding.options.metadataMode | Document metadata aggregation mode | EMBED
168-
|====
169166

0 commit comments

Comments
 (0)