Skip to content

Commit 7ee6a3b

Browse files
WendyRingWendyRing
authored
Merge pull request #275277 from MicrosoftDocs/release-build-postgresql
[Build 2024 ship room] PostgreSQL releases for //build 2024
2 parents d2d61b5 + 1f7626f commit 7ee6a3b

File tree

33 files changed

+914
-55
lines changed

33 files changed

+914
-55
lines changed

‎articles/postgresql/TOC.yml

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -169,6 +169,8 @@
169169
href: flexible-server/concepts-query-store-best-practices.md
170170
- name: Query Performance Insight
171171
href: flexible-server/concepts-query-performance-insight.md
172+
- name: Index tuning (preview)
173+
href: flexible-server/concepts-index-tuning.md
172174
- name: Intelligent tuning
173175
href: flexible-server/concepts-intelligent-tuning.md
174176
- name: Read replicas
@@ -392,6 +394,12 @@
392394
href: flexible-server/how-to-configure-and-access-logs.md
393395
- name: Intelligent performance
394396
items:
397+
- name: Index tuning
398+
items:
399+
- name: Configure index tuning
400+
href: flexible-server/how-to-configure-index-tuning.md
401+
- name: Use index recommendations
402+
href: flexible-server/how-to-get-and-apply-recommendations-from-index-tuning.md
395403
- name: Intelligent tuning
396404
items:
397405
- name: Azure portal
@@ -405,6 +413,8 @@
405413
displayName: replica
406414
- name: Extensions
407415
items:
416+
- name: Create embeddings with azure_local_ai (preview)
417+
href: ./flexible-server/generative-ai-azure-local-ai.md
408418
- name: Overview
409419
href: flexible-server/concepts-extensions.md
410420
- name: Azure AI (azure_ai)
@@ -416,7 +426,13 @@
416426
- name: Azure Cognitive Services
417427
href: flexible-server/generative-ai-azure-cognitive.md
418428
- name: Azure Machine Learning Services
419-
href: flexible-server/generative-ai-azure-machine-learning.md
429+
href: flexible-server/generative-ai-azure-machine-learning.md
430+
- name: In-database Embeddings (azure_local_ai)
431+
items:
432+
- name: Overview
433+
href: flexible-server/azure-local-ai.md
434+
- name: Create embeddings with azure_local_ai
435+
href: flexible-server/generative-ai-azure-local-ai.md
420436
- name: Azure Storage (pg_azure_storage)
421437
href: flexible-server/reference-pg-azure-storage.md
422438
- name: Vector similarity search (pgvector)

‎articles/postgresql/flexible-server/azure-local-ai.md

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
title: Create in-database embeddings with azure_local_ai extension
3+
description: Enable RAG patterns with in-database embeddings and vectors on Azure Database for PostgreSQL - Flexible Server.
4+
author: jojohnso-msft
5+
ms.author: jojohnso
6+
ms.reviewer: maghan
7+
ms.date: 05/08/2024
8+
ms.service: postgresql
9+
ms.subservice: flexible-server
10+
ms.topic: overview
11+
ms.custom:
12+
- build-2024
13+
# customer intent: As a user, I want to understand the overview and use cases of the azure_local_ai extension for Azure Database for PostgreSQL - Flexible Server.
14+
---
15+
16+
# What is the azure_local_ai extension for Azure Database for PostgreSQL - Flexible Server (Preview)
17+
18+
The azure_local_ai extension for Azure Database for PostgreSQL flexible server allows you to use registered, pretrained, open-source models deployed locally to your Azure Database for PostgreSQL server. These models can be used to create text embeddings that can provide context to your Retrieval Augmented Generation (RAG) pattern as you build rich generative AI applications.  The azure_local_ai extension enables the database to call locally deployed models to create vector embeddings from text data, simplifying the development process and reducing latency by removing the need to make more remote API calls to AI embedding models hosted outside of the PostgreSQL boundary. In this release, the extension deploys a single model, [multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small), to your Azure Database for PostgreSQL Flexible Server instance. Other third-party open-source models might become available for installation on an ongoing basis.
19+
20+
Local embeddings help customers:
21+
22+
- Reduce latency of embedding creation.
23+
24+
- Use embedding models at a predictable cost.
25+
26+
- Keep data within their database eliminating the need to transmit data to a remote endpoint.
27+
28+
> [!IMPORTANT]
29+
> The azure_local_ai extension is currently in preview. Microsoft's Open-source AI models for installation through the Azure Local AI extension are deemed Non-Microsoft Products under the Microsoft Product Terms. The customer's use of open-source AI models is governed by the separate license terms provided in product documentation associated with such models made available through the azure_local_ai extension.
30+
31+
## Enable the `azure_local_ai` extension (preview)
32+
33+
Before you can enable azure_local_ai on your Azure Database for PostgreSQL flexible server instance, you need to add it to your allowlist as described in [how to use PostgreSQL extensions](concepts-extensions.md) and check that it was correctly added by running the following SQL statement, `SHOW azure.extensions;`.
34+
35+
> [!IMPORTANT]
36+
> Hosting language models in the database requires a large memory footprint. To support this requirement, azure_local_ai is only supported on memory-optimized Azure SKUs.
37+
38+
39+
Select **Server parameters** from the Settings section of the Resource Menu in the Azure Database for PostgreSQL Flexible Server Azure portal page.
40+
41+
:::image type="content" source="media/azure-local-ai/pgsql-server-parameters-2.png" alt-text="Screenshot of PostgreSQL server parameters page.":::
42+
43+
Search for "extensions" or "azure.extensions"
44+
45+
:::image type="content" source="media/azure-local-ai/extensions-allow-list-1.png" alt-text="Screenshot of Extensions available to allowlist for Azure Database for Postgresql - Flexible server." lightbox="media/azure-local-ai/extensions-allow-list-1.png":::
46+
47+
Select AZURE_LOCAL_AI from the extensions list.
48+
49+
:::image type="content" source="media/azure-local-ai/extensions-allow-list-2.png" alt-text="Screenshot of Extensions allowlist screenshot for Azure Local AI extension." lightbox="media/azure-local-ai/extensions-allow-list-2.png":::
50+
51+
Select **Save** to apply the changes and begin the allowlist deployment process.
52+
53+
:::image type="content" source="media/azure-local-ai/extensions-allow-list-3.png" alt-text="Screenshot of Extensions saved to allowlist for Azure Local AI extension." lightbox="media/azure-local-ai/extensions-allow-list-3.png":::
54+
55+
You can monitor this deployment via the bell icon at the top of the Azure portal.
56+
57+
:::image type="content" source="media/azure-local-ai/extensions-allow-list-4.png" alt-text="Screenshot of Extensions allowlist deployment status for Azure Local AI extension.":::
58+
59+
Once the allowlist deployment is completed, you can continue with the installation process.
60+
61+
> [!NOTE]
62+
> Enabling Azure Local AI preview will deploy the [multilingual-e5-small](https://huggingface.co/intfloat/multilingual-e5-small) model to your Azure Database for PostgreSQL Flexible Server instance. The linked documentation provides licensing terms from the e5 team.
63+
> Additional third-party open-source models might become available for installation on an ongoing basis.
64+
65+
Now you can install the extension by connecting to your target database and running the [CREATE EXTENSION](https://www.postgresql.org/docs/current/sql-createextension.html) command. You need to repeat the command separately for every database in which you want the extension to be available.
66+
67+
List extensions are allowed on the database from the Azure portal - Server Parameters page.
68+
69+
```sql
70+
SHOW azure.extensions;
71+
```
72+
73+
Create the extension within the database.
74+
75+
```sql
76+
CREATE EXTENSION azure_local_ai;
77+
```
78+
79+
Installing the extension azure_local_ai creates the following schema:
80+
81+
- azure_local_ai: principal schema in which the extension creates tables, functions, and any other SQL-related object it requires to implement and expose its functionality.
82+
83+
> [!IMPORTANT]
84+
> You want to enable the [vector extension](how-to-use-pgvector.md)__,__ as it is required to store text embeddings in your PostgreSQL database.
85+
86+
## Functions provided by the azure_local_ai extension
87+
88+
The azure_local_ai extension provides a set of functions. These functions allow you to create vector embeddings from text data, making it easier to develop generative AI applications. The extension offers functions for creating embeddings, getting settings, and more. By using these functions, you can simplify the development process and reduce latency by eliminating the need for additional remote API calls to AI embedding models hosted outside of the PostgreSQL boundary.
89+
90+
| Schema | Name | Result data type | Argument data types |
91+
|---|---|---|---|
92+
| `azure_local_ai` | create_embeddings | TABLE(embedding real[]) | model_uri text, inputs text[], batch_size bigint DEFAULT 128, timeout_ms integer DEFAULT 3600000 |
93+
| `azure_local_ai` | create_embeddings | real[] | model_uri text, input text, timeout_ms integer DEFAULT 3600000 |
94+
| `azure_local_ai` | get_setting | jsonb | keys text[] DEFAULT ARRAY[]::text[], timeout_ms integer DEFAULT 3600000 |
95+
| `azure_local_ai` | get_setting | text | key text, timeout_ms integer DEFAULT 3600000 |
96+
| `azure_local_ai` | model_metadata | jsonb | model_uri text |
97+
98+
These can be displayed via the PSQL command,
99+
100+
```psql
101+
\df azure_local_ai.*
102+
```
103+
104+
## `azure_local_ai.create_embeddings`
105+
106+
The azure_local_ai extension allows you to create and update embeddings both in scalar and batch format, invoking the locally deployed LLM.
107+
108+
```sql
109+
azure_local_ai.create_embeddings(model_uri text, input text, batch_size bigint DEFAULT 128, timeout_ms integer DEFAULT 3600000);
110+
```
111+
```sql
112+
azure_local_ai.create_embeddings(model_uri text, array[inputs [text]], batch_size bigint DEFAULT 128, timeout_ms integer DEFAULT 3600000);
113+
```
114+
115+
### Arguments
116+
117+
#### `model_uri`
118+
119+
`text` name of the text embedding model invoked to create the embedding.
120+
121+
#### `input`
122+
123+
`text` or `text[]` single text or array of texts, depending on the overload of the function used, for which embeddings are created.
124+
125+
#### `batch_size`
126+
127+
`bigint DEFAULT 128` number of records to process at a time (only available for the overload of the function for which parameter `input` is of type `text[]`).
128+
129+
#### `timeout_ms`
130+
131+
`integer DEFAULT 3600000` timeout in milliseconds after which the operation is stopped.
132+
133+
134+
Simple create embeddings examples:
135+
136+
```sql
137+
SELECT azure_local_ai.create_embeddings('model_uri TEXT', 'query: input TEXT');
138+
```
139+
140+
```sql
141+
SELECT azure_local_ai.create_embeddings('multilingual-e5-small:v1', 'query: Vector databases are awesome');
142+
```
143+
144+
```sql
145+
SELECT azure_local_ai.create_embeddings('model_uri TEXT', array['input TEXT', 'input TEXT']);
146+
```
147+
148+
```sql
149+
SELECT azure_local_ai.create_embeddings('multilingual-e5-small:v1', array['Hello', 'World']);
150+
```
151+
152+
#### Check the azure_local_ai extension version
153+
154+
```sql
155+
SELECT * FROM pg_available_extensions
156+
WHERE NAME ='azure_local_ai';
157+
```
158+
159+
## ONNX Runtime Configuration
160+
161+
### `azure_local_ai.get_setting`
162+
Used to obtain current values of configuration options.
163+
164+
```sql
165+
SELECT azure_local_ai.get_setting(key TEXT)
166+
```
167+
168+
azure_local_ai supports reviewing the configuration parameters of ONNX Runtime thread-pool within the ONNX Runtime Service. Changes are not allowed at this time. [See ONNX Runtime performance tuning.](https://onnxruntime.ai/docs/performance/tune-performance/threading.html)
169+
170+
171+
#### Arguments
172+
173+
##### Key
174+
175+
Valid values for the `key` are:
176+
177+
- `intra_op_parallelism`: Sets total number of threads used for parallelizing single operator by ONNX Runtime thread-pool. By default, we maximize the number of intra ops threads as much as possible as it improves the overall throughput much (all available cpus by default).
178+
- `inter_op_parallelism`: Sets total number of threads used for computing multiple operators in parallel by ONNX Runtime thread-pool. By default, we set it to minimum possible thread, which is 1. Increasing it often hurts performance due to frequent context switches between threads.
179+
- `spin_control`: Switches ONNX Runtime thread-pool's spinning for requests. When disabled, it uses less cpu and hence causes more latency. By default, it is set to true (enabled).
180+
181+
#### Return type
182+
`TEXT` representing the current value of the selected setting.
183+
184+
185+
186+
## Related content
187+
- [Concepts: Generate vector embeddings with azure_local_ai on Azure Database for PostgreSQL Flexible Server (Preview)](generative-ai-azure-local-ai.md)
188+
- [How to enable and use `pgvector` on Azure Database for PostgreSQL - Flexible Server](how-to-use-pgvector.md)

0 commit comments

Comments
 (0)