Integrate Azure OpenAI as an embedding provider
Integrate Microsoft Azure OpenAI as an external embedding provider for Astra DB vectorize to leverage Azure OpenAI’s embeddings API within Astra DB Serverless.
Prerequisites
To configure the Azure OpenAI embedding provider integration, you need the following:
-
An active Astra account with the Organization Administrator role.
-
A Serverless (Vector) database.
If this is your first time using Astra DB, follow the Quickstart to create a database and connect to it with an API client.
-
A paid Azure OpenAI account.
Create the Azure OpenAI API key
Log in to your Azure OpenAI account and create a new API key with unrestricted access to the API. Make sure to copy the API key to a secure location.
Don’t modify or delete the API key in your Azure OpenAI account after you’ve added it to Astra DB. This breaks the integration. For more information, see Embedding provider authentication. |
Add the Azure OpenAI integration to your organization
Use the Astra Portal to add the Azure OpenAI embedding provider integration to your Astra DB organization:
-
In the Astra Portal navigation menu, click Integrations.
-
In the All Integrations section, select Azure OpenAI Embedding provider.
-
Click Add integration.
-
In the Add Integration dialog, do the following:
-
Enter a unique API key name.
You can’t change API key names. Make sure the name is meaningful and that it helps you identify your Azure OpenAI API key in Astra DB.
-
Enter your Azure OpenAI API key.
-
In the Add databases to scope section, select a Serverless (Vector) database that you want to use the Azure OpenAI API key.
When you create a collection in a scoped database, you can choose any of the API keys that are available to the database. Astra DB uses the API key to request embeddings from your embedding provider when you load data into the collection.
You can add up to 10 databases at once, and you can add more databases later.
For greater access control, you can add multiple API keys, and each API key can have different scoped databases. Additionally, you can add the same database to multiple API key scopes.
For example, you can have a few broadly-scoped API keys or many narrowly-scoped API keys.
For more information, see Embedding provider authentication, Scoped databases, and Manage scoped databases.
-
-
Click Add Integration.
The Azure OpenAI integration switches to
ACTIVE, and your API key and its scoped databases appear in the API keys section. If you want to add more API keys for this integration, click Add API key.
When you create collections in the scoped databases, you can select the Azure OpenAI integration, and then use it to generate embeddings.
Add the Azure OpenAI integration to a new collection
Before you can use the Azure OpenAI integration to generate embeddings, you must add the integration to a new collection.
You can’t change a collection’s embedding provider or embedding generation method after you create it. To use a different embedding provider, you must create a new collection with a different embedding provider integration. |
-
Astra Portal
-
Python
-
TypeScript
-
Java
-
curl
-
In the Astra Portal, go to Databases, and then select your Serverless (Vector) database.
-
Click Data Explorer.
-
In the Namespace field, select the namespace where you want to create the collection, or use the default namespace, which is named
default_keyspace
. -
Click Create Collection.
-
In the Create collection dialog, enter a name for the collection. Collection names can have no more than 50 characters.
-
Turn on Vector-enabled collection.
-
Under Embedding generation method, select the Azure OpenAI embedding provider integration.
If the integration isn’t listed, follow the steps in Add the Azure OpenAI integration to your organization and Manage scoped databases to make sure the integration is active and that your database is scoped to at least one API key.
-
Complete the following fields:
-
API key: The API key that you want the collection to use to access your embedding provider and generate embeddings. This field is only active if the database is scoped to multiple Azure OpenAI API keys.
-
Resource name: The name of your Azure OpenAI resource. For more information about resources, see the Azure OpenAI documentation.
-
Deployment ID: The name of your model deployment. For more information about model deployments, see the Azure OpenAI documentation.
-
Embedding model: The model that you want to use to generate embeddings. The available models are:
text-embedding-3-small
,text-embedding-3-large
,text-embedding-ada-002
. For Azure OpenAI, you must select the model that matches the one you deployed to your Deployment ID in Azure. -
Dimensions: The number of dimensions that you want the generated vectors to have. Most models automatically populate the Dimensions. You can edit this field if the model supports a range of dimensions or the embedding provider integration uses an endpoint-defined model. Your chosen embedding model must support the specified number of dimensions.
-
Similarity metric: The method you want to use to calculate vector similarity scores. The available metrics are Cosine, Dot Product, and Euclidean.
-
-
Click Create collection.
Use the Python client to create a collection that uses the Azure OpenAI integration.
Initialize the client
If you haven’t done so already, initialize the client before creating a collection:
import os
from astrapy import DataAPIClient
from astrapy.constants import VectorMetric
from astrapy.info import CollectionVectorServiceOptions
# Initialize the client and get a "Database" object
client = DataAPIClient(os.environ["ASTRA_DB_APPLICATION_TOKEN"])
database = client.get_database(os.environ["ASTRA_DB_API_ENDPOINT"])
print(f"* Database: {database.info().name}\n")
Create a collection integrated with Azure OpenAI:
collection = database.create_collection(
"COLLECTION_NAME",
metric=VectorMetric.COSINE,
dimension=MODEL_DIMENSIONS, # optional
service=CollectionVectorServiceOptions(
provider="azureOpenAI",
model_name="MODEL_NAME",
authentication={
"providerKey": "API_KEY_NAME",
},
parameters={
"resourceName": "RESOURCE_NAME",
"deploymentId": "DEPLOYMENT_ID",
},
),
)
print(f"* Collection: {collection.full_name}\n")
Replace the following:
-
COLLECTION_NAME
: The name for your collection. -
API_KEY_NAME
: The name of the Azure OpenAI API key that you want to use for your collection. Must be the name of an existing Azure OpenAI API key in the Astra Portal. -
MODEL_NAME
: The desired model to use to generate embeddings. For Azure OpenAI, the supported models aretext-embedding-3-small
,text-embedding-3-large
,text-embedding-ada-002
. -
MODEL_DIMENSIONS
: The number of dimensions that you want the generated vectors to have. Your embedding model must support the specified number of dimensions.If your model has a default dimension value, you can omit
dimension
.You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.
-
RESOURCE_NAME
: The name of your Azure OpenAI resource. For more information about resources, see the Azure OpenAI documentation. -
DEPLOYMENT_ID
: The name of your model deployment. For more information about model deployments, see the Azure OpenAI documentation.
Use the TypeScript client to create a collection that uses the Azure OpenAI integration.
Initialize the client
If you haven’t done so already, initialize the client before creating a collection:
import { DataAPIClient, VectorDoc, UUID } from '@datastax/astra-db-ts';
const { ASTRA_DB_APPLICATION_TOKEN, ASTRA_DB_API_ENDPOINT } = process.env;
// Initialize the client and get a 'Db' object
const client = new DataAPIClient(ASTRA_DB_APPLICATION_TOKEN);
const db = client.db(ASTRA_DB_API_ENDPOINT);
console.log(`* Connected to DB ${db.id}`);
Create a collection integrated with Azure OpenAI:
(async function () {
const collection = await db.createCollection('COLLECTION_NAME', {
vector: {
dimension: MODEL_DIMENSIONS, // optional
service: {
provider: 'azureOpenAI',
modelName: 'MODEL_NAME',
authentication: {
providerKey: 'API_KEY_NAME',
},
parameters: {
resourceName: 'RESOURCE_NAME',
deploymentId: 'DEPLOYMENT_ID',
},
},
},
});
console.log(`* Created collection ${collection.namespace}.${collection.collectionName}`);
Replace the following:
-
COLLECTION_NAME
: The name for your collection. -
API_KEY_NAME
: The name of the Azure OpenAI API key that you want to use for your collection. Must be the name of an existing Azure OpenAI API key in the Astra Portal. -
MODEL_NAME
: The desired model to use to generate embeddings. For Azure OpenAI, the supported models aretext-embedding-3-small
,text-embedding-3-large
,text-embedding-ada-002
. -
MODEL_DIMENSIONS
: The number of dimensions that you want the generated vectors to have. Your embedding model must support the specified number of dimensions.If your model has a default dimension value, you can omit
dimension
.You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.
-
RESOURCE_NAME
: The name of your Azure OpenAI resource. For more information about resources, see the Azure OpenAI documentation. -
DEPLOYMENT_ID
: The name of your model deployment. For more information about model deployments, see the Azure OpenAI documentation.
Use the Java client to create a collection that uses the Azure OpenAI integration.
Initialize the client
If you haven’t done so already, initialize the client before creating a collection:
import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.Database;
import com.datastax.astra.client.model.CollectionOptions;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.FindIterable;
import com.datastax.astra.client.model.FindOptions;
import com.datastax.astra.client.model.SimilarityMetric;
import static com.datastax.astra.client.model.SimilarityMetric.COSINE;
public class Quickstart {
public static void main(String[] args) {
// Loading Arguments
String astraToken = System.getenv("ASTRA_DB_APPLICATION_TOKEN");
String astraApiEndpoint = System.getenv("ASTRA_DB_API_ENDPOINT");
// Initialize the client
DataAPIClient client = new DataAPIClient(astraToken);
System.out.println("Connected to AstraDB");
Database db = client.getDatabase(astraApiEndpoint);
System.out.println("Connected to Database.");
Create a collection integrated with Azure OpenAI:
Map<String, Object > params = new HashMap<>();
params.put("resourceName", "RESOURCE_NAME");
params.put("deploymentId", "DEPLOYMENT_ID");
CollectionOptions.CollectionOptionsBuilder builder = CollectionOptions
.builder()
.vectorSimilarity(SimilarityMetric.COSINE)
.vectorDimension(MODEL_DIMENSIONS) // optional
.vectorize("azureOpenAI","MODEL_NAME", "API_KEY_NAME", params);
Collection<Document> collection = db
.createCollection("COLLECTION_NAME", builder.build());
Replace the following:
-
COLLECTION_NAME
: The name for your collection. -
API_KEY_NAME
: The name of the Azure OpenAI API key that you want to use for your collection. Must be the name of an existing Azure OpenAI API key in the Astra Portal. -
MODEL_NAME
: The desired model to use to generate embeddings. For Azure OpenAI, the supported models aretext-embedding-3-small
,text-embedding-3-large
,text-embedding-ada-002
. -
MODEL_DIMENSIONS
: The number of dimensions that you want the generated vectors to have. Your embedding model must support the specified number of dimensions.If your model has a default dimension value, you can omit
dimension
.You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.
-
RESOURCE_NAME
: The name of your Azure OpenAI resource. For more information about resources, see the Azure OpenAI documentation. -
DEPLOYMENT_ID
: The name of your model deployment. For more information about model deployments, see the Azure OpenAI documentation.
Use the Data API to create a collection that uses the Azure OpenAI integration:
curl -sS --location -X POST "$ASTRA_DB_API_ENDPOINT/api/json/v1/default_keyspace" \
--header "Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"createCollection": {
"name": "COLLECTION_NAME",
"options": {
"vector": {
"dimension": MODEL_DIMENSIONS, # optional
"metric": "cosine",
"service": {
"provider": "azureOpenAI",
"modelName": "MODEL_NAME",
"authentication": {
"providerKey": "API_KEY_NAME"
},
"parameters": {
"resourceName": "RESOURCE_NAME",
"deploymentId": "DEPLOYMENT_ID"
}
}
}
}
}
}' | jq
Replace the following:
-
COLLECTION_NAME
: The name for your collection. -
API_KEY_NAME
: The name of the Azure OpenAI API key that you want to use for your collection. Must be the name of an existing Azure OpenAI API key in the Astra Portal. -
MODEL_NAME
: The desired model to use to generate embeddings. For Azure OpenAI, the supported models aretext-embedding-3-small
,text-embedding-3-large
,text-embedding-ada-002
. -
MODEL_DIMENSIONS
: The number of dimensions that you want the generated vectors to have. Your embedding model must support the specified number of dimensions.If your model has a default dimension value, you can omit
dimension
.You can use the Data API to find supported embedding providers and their configuration parameters, including dimensions ranges and default dimensions.
-
RESOURCE_NAME
: The name of your Azure OpenAI resource. For more information about resources, see the Azure OpenAI documentation. -
DEPLOYMENT_ID
: The name of your model deployment. For more information about model deployments, see the Azure OpenAI documentation.
If you get a Serverless (Vector) databases created after June 24, 2024 can have up to 10 collections. Databases created before this date can have up to 5 collections. The collection limit is based on Storage Attached Indexing (SAI). |
After you create a collection, load data into the collection.
Load and search data with vectorize
-
Load vector data into your vectorize-integrated collection.
When you load structured JSON or CSV data, the Vector Field specifies field to use to generate embeddings with
$vectorize
. -
After loading data, you can perform a similarity search using text, rather than a vector.
Manage scoped databases
For each API key, you select the databases that can use that API key. These are referred to as scoped databases.
To change the scoped databases for an existing Azure OpenAI API key, do the following:
-
In the Astra Portal navigation menu, click Integrations, and then select Azure OpenAI.
-
In the API keys section, expand each API key to show the list of scoped databases.
-
Add or remove databases from each API key’s scope, as needed:
-
To remove a database from the API key’s scope, click
Delete, enter the Database name, and then click Remove scope. -
To add a database to the API key’s scope, click
More, select Add database, select the Serverless (Vector) database that you want to add to the scope, and then click Add database.
-
Remove Azure OpenAI API keys
Removing API keys immediately disables Removing API keys from Astra DB Serverless does not delete them from your Azure OpenAI account. |
To remove API keys, do the following:
-
In the Astra Portal navigation menu, click Integrations, and then select Azure OpenAI Embedding provider.
-
In the API keys section, locate the API key that you want to remove, click
More, and then select Remove API key. -
In the confirmation dialog, enter the API key name, and then click Remove key.
-
In your Azure OpenAI account, delete the API key if you don’t plan to reuse it.
-
If you no longer want to use this embedding provider or you are not rotating the API key, then you must recreate any collections that used the removed API key to generate embeddings. For more information, see Change providers or credentials.
Rotate Azure OpenAI API keys
To rotate API keys, you must remove the API key, and then recreate it with the same name and scoped databases.
Removing the API key immediately disables $vectorize
embedding generation for any collections that used that API key.
Vectorize remains unavailable until you add the new API key to the Azure OpenAI integration.
For more information, see Change providers or credentials.
To rotate API keys, do the following:
-
In your Azure OpenAI, create a new API key.
-
Remove the API key that you want to rotate. Make a note of the API key’s name and scoped databases. When you recreate the API key, it must have the exact same name and scope.
-
In the Astra Portal navigation menu, click Integrations, and then select Azure OpenAI Embedding provider.
-
In the API keys section, add a new API key with the same name as the removed API key.
If the name doesn’t match, any collections that used the removed API key can’t detect the replacement API key.
-
Add all relevant databases to the new API key’s scoped databases.
At minimum, you must add all databases that used the removed API key so that the collections in those databases can detect the replacement API key. To ensure that you don’t miss any databases, DataStax recommends adding all of the databases that were in the removed API key’s scope.
Remove the Azure OpenAI integration from your organization
To remove the Azure OpenAI embedding provider integration from your Astra organization remove all existing Azure OpenAI API keys, and then recreate any collections that used the integration to generate embeddings.