Integrate Azure OpenAI as an embedding provider

Integrate Azure OpenAI as an external embedding provider for Astra DB vectorize to leverage Azure OpenAI’s embeddings API within Astra DB Serverless.

Prerequisites

To integrate Azure OpenAI as an external embedding provider, you’ll need the following:

Create an Azure OpenAI API key

Log into your Azure OpenAI account and create a new API key with unrestricted access to the API. Make sure to copy the 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. This will break the integration.

Add the Azure OpenAI integration to your organization

Use the Astra Portal to add the Azure OpenAI embedding provider integration to your Astra organization:

  1. In the Astra Portal navigation menu, click Integrations.

  2. In the All Integrations section, select Azure OpenAI Embedding provider.

  3. Click Add integration.

  4. In the Add Integration dialog, do the following:

    1. 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.

    2. Enter your Azure OpenAI API key.

    3. Under Add databases to API key scope, use the dropdown menu to select a Serverless (Vector) database that you want scoped to your Azure OpenAI API key.

      You can select up to 10 databases at a time. You can add more databases later if needed.

  5. Click Add Integration.

    Your API key and its associated databases appear in the API keys section.

You can now select your Azure OpenAI integration as an embedding provider when you create a collection in a scoped database.

To add another API key with additional scopes, click Add API key and repeat the previous steps.

You can scope the same database to multiple API keys. This lets you select the most appropriate API key for each collection.

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.

  • Astra Portal

  • Python

  • TypeScript

  • Java

Use the Astra Portal to add the Azure OpenAI integration to a new collection:

  1. In the Astra Portal, go to Databases, and then select your Serverless (Vector) database.

  2. Click Data Explorer.

  3. Optional: Use the Namespace dropdown to select the namespace where you want to create the collection. Otherwise, leave default_keyspace selected to create the collection in the default namespace.

  4. Click Create Collection.

  5. In the Create collection dialog, enter a name for the new collection in the Collection name field.

  6. Under Embedding generation method, select the Azure OpenAI embedding provider integration.

  7. Select the API key that you want to use for your collection. This dropdown menu is only active if you’ve scoped your database to multiple API keys within the same integration.

  8. Select the Embedding model that you want to use to generate embeddings.

  9. If your embedding model supports a range of dimensions, enter the number of Dimensions that you want the generated vectors to have.

  10. Select a Similarity metric that your embedding model will use to compare vectors.

    The available metrics are:

  11. Click Create collection.

    If you get a Collection Limit Reached message, you’ll need to delete a collection before you can create a new one.

An empty collection appears in the list of collections. You can now load data into this collection.

Use the Python client to add the Azure OpenAI integration to a new collection.

# Create a collection. The default similarity metric is cosine. If you're not
# sure what dimension to set, use whatever dimension vector your embeddings
# model produces.
collection = database.create_collection(
    "vectorize_test",
    metric=VectorMetric.COSINE,  # or simply "cosine"
    service=CollectionVectorServiceOptions(
        provider="azureOpenAI",
        model_name="text-embedding-ada-002",
        authentication={
            "providerKey": "API_KEY_NAME",
        },
    ),
    check_exists=False,
)
print(f"* Collection: {collection.full_name}\n")

Use the TypeScript client to add the Azure OpenAI integration to a new collection.

// Schema for the collection (VectorDoc adds the $vector field)
interface Idea extends VectorDoc {
  idea: string,
}

(async function () {
  // Create a typed, vector-enabled collection. The default metric is cosine.
  // If you're not sure what dimension to set, use whatever dimension vector
  // your embeddings model produces.
  const collection = await db.createCollection('vector_test', {
    vector: {
      metric: 'cosine',
      service: {
        provider: "azureOpenAI",
        modelName: "text-embedding-ada-002",
        authentication: {
          providerKey: "API_KEY_NAME",
        },
      },
    },
    checkExists: false,
  });
  console.log(`* Created collection ${collection.namespace}.${collection.collectionName}`);

Use the Java client to add the Azure OpenAI integration to a new collection.

    // Create a collection. The default similarity metric is cosine. If you're
    // not sure what dimension to set, use whatever dimension vector your
    // embeddings model produces.
    Collection collection = db.createCollection("vector_test",
            CollectionOptions.builder()
                    .vectorSimilarity(SimilarityMetric.COSINE)
                    .vectorDimension(1536)
                    .vectorize("azureOpenAI", "text-embedding-ada-002", "test")
                    .build());
    System.out.println("Created a collection");

Load data using vectorize to auto-generate embeddings

Use the following methods to load vector data into a collection and use $vectorize to auto-generate embeddings.

  • Astra Portal

  • Python

  • TypeScript

  • Java

Use the Astra Portal to load a dataset from a JSON or a CSV file.

  1. In the Astra Portal, go to Databases, and then select a database that contains a collection that uses the Azure OpenAI integration.

  2. Click Data Explorer.

  3. Select the collection that uses the Azure OpenAI integration.

  4. Click Load Data.

  5. In the Load Data dialog, click Select File.

  6. Select the file on your computer that contains your dataset.

    Once the file upload is complete, the first ten rows of your data appear in the Data Preview section.

    If you get a Selected embedding does not match collection dimensions error, you need to create a new collection with vector dimensions that match your dataset.

  7. Use the Vector Field dropdown to select the field that you want to auto-generate embeddings for.

    The Load Data dialog with Vector Field dropdown expanded.

    The data importer will apply the top-level $vectorize key to the Vector Field, and automatically generate an embedding vector from its contents. The resulting documents in the collection will have the actual text stored in the special $vectorize field, and the resulting embedding stored in the $vector field.

  8. Optional: Configure field data types.

    In the Data Preview section, use the drop-down controls to change the data type for each field or column.

    The options are:

    • String

    • Number

    • Array

    • Object

    • Vector

    Data type selections you make in the Data Preview section only apply to the initial data that you load (with the exception of Vector, which permanently maps the field to the reserved key $vector). These selections aren’t fixed in the schema, and don’t apply to documents inserted later on. The same field can be a string in one document, and a number in another. You can also have different sets of fields in different documents in the same collection.

  9. Click Load Data.

Once your dataset has loaded, you can interact with it and do a vector search using the Data Explorer and the client APIs.

Use the Python client to load data into your database.

# Insert documents into the collection.
# (UUIDs here are version 7.)
documents = [
    {
        "_id": UUID("018e65c9-df45-7913-89f8-175f28bd7f74"),
        "$vectorize": "ChatGPT integrated sneakers that talk to you",
    },
    {
        "_id": UUID("018e65c9-e1b7-7048-a593-db452be1e4c2"),
        "$vectorize": "An AI quilt to help you sleep forever",
    },
    {
        "_id": UUID("018e65c9-e33d-749b-9386-e848739582f0"),
        "$vectorize": "A deep learning display that controls your mood",
    },
]
try:
    insertion_result = collection.insert_many(documents)
    print(f"* Inserted {len(insertion_result.inserted_ids)} items.\n")
except InsertManyException:
    print("* Documents found on DB already. Let's move on.\n")

Use the TypeScript client to load data into your database.

  // Insert documents into the collection (using UUIDv7s)
  const documents = [
    {
      _id: new UUID('018e65c9-df45-7913-89f8-175f28bd7f74'),
      $vectorize: 'ChatGPT integrated sneakers that talk to you',
    },
    {
      _id: new UUID('018e65c9-e1b7-7048-a593-db452be1e4c2'),
      $vectorize: 'An AI quilt to help you sleep forever',
    },
    {
      _id: new UUID('018e65c9-e33d-749b-9386-e848739582f0'),
      $vectorize: 'A deep learning display that controls your mood',
    },
  ];

  try {
    const inserted = await collection.insertMany(documents);
    console.log(`* Inserted ${inserted.insertedCount} items.`);
  } catch (e) {
    console.log('* Documents found on DB already. Let\'s move on!');
  }

Use the Java client to load data into your database.

    // Insert documents into the collection
    collection.insertMany(
            new Document("1").vectorize("ChatGPT integrated sneakers that talk to you"),
            new Document("2").vectorize("An AI quilt to help you sleep forever"),
            new Document("3").vectorize("A deep learning display that controls your mood"));
    System.out.println("Inserted documents into the collection");

Search your data with vectorize

Perform a similarity search using text, rather than a vector.

  • Astra Portal

  • Python

  • TypeScript

  • Java

Use the Astra Portal to perform a search with vectorize:

  1. In the Astra Portal, go to Databases, and then select your Serverless (Vector) database.

  2. Click Data Explorer.

  3. Select the Namespace and Collection that contain the data you want to view.

    Your data is displayed in the Collection Data section. The field you configured to auto-generate embeddings is notated with ($vectorize) in the column title. The $vector field contains the generated embeddings.

  4. Enter a text query into the Hybrid Search field, and then click Apply.

    Astra DB auto-generates a vector from the text query and performs a similarity search. The search uses the similarity metric that you chose when you created the collection.

  5. Optional: Use Add Filter to filter your search results by the other fields in the collection. For more information about using filters, see Add a metadata filter.

The Collection Data section updates to show the rows that match your search criteria.

Use the Python client to perform a search with vectorize:

# Perform a similarity search
query = "I'd like some talking shoes"
results = collection.find(
    sort={"$vectorize": query},
    limit=2,
    projection={"$vectorize": True},
    include_similarity=True,
)
print(f"Vector search results for '{query}':")
for document in results:
    print("    ", document)

Use the TypeScript client to perform a search with vectorize:

  // Perform a similarity search
  const cursor = await collection.find({}, {
    sort: { $vectorize: "ChatGPT" },
    limit: 2,
    includeSimilarity: true,
  });

  console.log('* Search results:')
  for await (const doc of cursor) {
    console.log('  ', doc.text, doc.$similarity);
  }

Use the Java client to perform a search with vectorize:

    // Perform a similarity search
    FindIterable<Document> resultsSet = collection.find(
            new FindOptions().sort("ChatGPT").limit(10));
    resultsSet.forEach(System.out::println);

Manage database scopes

To manage database scopes for an existing Azure OpenAI API key:

  1. In the Astra Portal navigation menu, click Integrations, and then select Azure OpenAI Embedding provider.

  2. In the API keys section, locate your API key and then click the chevron_right expander arrow to show the list of scoped databases.

  3. To remove a scoped database, click delete Delete.

    In the confirmation dialog, enter the Database name, and then click Remove scope.

  4. To add a database scope, click more_vert More, and then select Add scope.

    Under Add databases to API key scope, use the dropdown menu to select a Serverless (Vector) database, and then click Add scope.

Remove an existing API key from the Azure OpenAI integration

Ensure that no active collections are using an API key before removing it, as it will immediately disable $vectorize embedding generation for those collections.

You cannot assign a new API key to an existing collection.

To remove an existing Azure OpenAI API key:

  1. In the Astra Portal navigation menu, click Integrations, and then select Azure OpenAI Embedding provider.

  2. In the API keys section, locate the API key you want to remove, click more_vert More, and then select Remove API key.

  3. In the confirmation dialog, enter the API key name, and then click Remove key.

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.

Was this helpful?

Give Feedback

How can we improve the documentation?

© 2024 DataStax | Privacy policy | Terms of use

Apache, Apache Cassandra, Cassandra, Apache Tomcat, Tomcat, Apache Lucene, Apache Solr, Apache Hadoop, Hadoop, Apache Pulsar, Pulsar, Apache Spark, Spark, Apache TinkerPop, TinkerPop, Apache Kafka and Kafka are either registered trademarks or trademarks of the Apache Software Foundation or its subsidiaries in Canada, the United States and/or other countries. Kubernetes is the registered trademark of the Linux Foundation.

General Inquiries: +1 (650) 389-6000, info@datastax.com