Skip to main content

text2vec-aws

Added in v1.22.5

Starting in v1.22.5, AWS Bedrock is supported.

Added in v1.24.0

Starting in v1.24.0, AWS Sagemaker is supported.

The text2vec-aws module allows Weaviate to access AWS Bedrock and AWS Sagemaker services.

If you need to run your own embedding service, use Sagemaker. Bedrock uses AWS models.

Considerations

  • This module is available on Weaviate Cloud Services (WCS).
  • Bedrock and Sagemaker are third party APIs. You must provide AWS API credentials.
  • Bedrock requires a model.
    • There is no default Bedrock model set for this module.
    • You must request access from AWS Bedrock to make models available in your account.
    • Not all AWS Bedrock models are supported. See Supported models.
    • If you set "service": "bedrock"``, set a model as well. For example, "model": "amazon.titan-embed-text-v1"`
    • Set a distance metric in your class configuration that corresponds to the model you use.
  • These APIs may incur costs. Before vectorizing large amounts of data, check the pricing pages.
  • Enabling this module enables the nearText search operator.

Where to set module parameters

The module accepts parameters through the request header, collection configuration, or environment variables. Some parameters (such as the API key) can be set in multiple ways.

Where the same parameter can be set in multiple ways, setting it at query-time through the HTTP request header (if possible) will have the highest precedence.

We suggest you only set any given parameter in one place to avoid confusion.

API Authentication

You must provide access key based AWS credentials to use the API, including an AWS access key and a corresponding AWS secret access key. You can set them as environment variables, or provide them at query time.

Weaviate instance configuration

Docker Compose file

To use text2vec-aws, enable it in your Docker Compose file (docker-compose.yml).

Parameters

ParameterTypeOptionalDefaultDescription
AWS_ACCESS_KEYstringyesnoneYour AWS access key. An alternative for AWS_ACCESS_KEY_ID.
AWS_ACCESS_KEY_IDstringyesnoneYour AWS access key. An alternative for AWS_ACCESS_KEY.
AWS_SECRET_KEYstringyesnoneYour AWS secret access key. An alternative for AWS_SECRET_ACCESS_KEY.
AWS_SECRET_ACCESS_KEYstringyesnoneYour AWS secret access key. An alternative for AWS_SECRET_KEY.
DEFAULT_VECTORIZER_MODULEstringyesnoneThe default vectorizer module. To make text2vec-aws the default vectorizer, set this parameter to text2vec-aws.
ENABLE_MODULESstringnononeSet text2vec-aws to enable the module.
SERVICEstringyesbedrockMust be bedrock or sagemaker.

Example

This configuration does the following:

  • Enables the text2vec-aws vectorizer
  • Sets text2vec-aws as the default vectorizer
  • Sets AWS authentication credentials
---
version: '3.4'
services:
weaviate:
image: cr.weaviate.io/semitechnologies/weaviate:1.24.0
restart: on-failure:0
ports:
- 8080:8080
- 50051:50051
environment:
QUERY_DEFAULTS_LIMIT: 20
AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
PERSISTENCE_DATA_PATH: "./data"
ENABLE_MODULES: text2vec-aws
DEFAULT_VECTORIZER_MODULE: text2vec-aws
AWS_ACCESS_KEY: sk-foobar # Optional. Can be set at query time.
AWS_SECRET_KEY: sk-foobar # Optional. Can be set at query time.
CLUSTER_HOSTNAME: 'node1'
...

Class configuration

To configure module behavior for a collection, set collection level values in the Weaviate schema.

API settings

Parameters

ParameterRequiredDefaultPurpose
modelNoNONEThe model to use with Bedrock. See supported models.
regionYesNONEAWS region name. For example, us-east-1.

Example

The following example configures the Document class to set the following parameters:

  • vectorizer: text2vec-aws
  • distance metric: cosine
  • service: "sagemaker"
  • endpoint: AWS provides this value when you configure sagemaker
  • AWS region: us-east-1
{
"classes": [
{
"class": "Document",
"description": "A class called document",
"vectorizer": "text2vec-aws",
"vectorIndexConfig": {
"distance": "cosine"
},
"moduleConfig": {
"text2vec-aws": {
"service": "sagemaker"
"endpoint": "YOUR_AWS_ENDPOINT" // REQUIRED with "sagemaker"
"region": "us-east-1" // REQUIRED
}
},
}
]
}

Vectorizer settings

To configure vectorization for collections and properties, use the moduleConfig section in the collection definition.

SettingLevelDefaultDescription
vectorizercollectionnoneThe module that vectorizes the data.
vectorizeClassNamecollectiontrueWhen true, vectorize the class name.
skippropertyfalseWhen true, does not vectorize the property.
vectorizePropertyNamepropertyfalseWhen true, does not vectorize the property name.

Example

{
"classes": [
{
"class": "Document",
"description": "A class called document",
"vectorizer": "text2vec-aws",
"vectorIndexConfig": {
"distance": "cosine"
},
"moduleConfig": {
"text2vec-aws": {
"model": "amazon.titan-embed-text-v1", // REQUIRED
"region": "us-east-1" // REQUIRED
"vectorizeClassName": false
}
},
"properties": [
{
"name": "content",
"dataType": ["text"],
"description": "Content that will be vectorized",
"moduleConfig": {
"text2vec-aws": {
"skip": false,
"vectorizePropertyName": false
}
}
}
]
}
]
}

Query-time parameters

To supply parameters at query time, adding them to the HTTP header.

HTTP HeaderValuePurpose
"X-AWS-Access-Key""YOUR-AWS-API-ACCESS-KEY"Your AWS access key.
"X-AWS-Secret-Key""YOUR-AWS-API-SECRET-KEY"Your AWS secret access key

Additional information

Supported models

text2vec-aws supports these models:

  • amazon.titan-embed-text-v1
  • cohere.embed-english-v3
  • cohere.embed-multilingual-v3

Distance metric

You can change the distance metric used for vector searches. cosine distance is a good starting point. For supported distance metrics, see Distance metrics.

Consult the documentation of the model you are using to see which distance metrics are appropriate.

API rate limits

This module uses your AWS credentials. API limits that restrict your AWS account also apply to the module. When the API returns a rate limited error, Weaviate returns an error message.

Import throttling

If your API access is rate limited, consider throttling imports within your application.

See code example
from weaviate import Client
import time

def configure_batch(client: Client, batch_size: int, batch_target_rate: int):
"""
Configure the weaviate client's batch so it creates objects at `batch_target_rate`.

Parameters
----------
client : Client
The Weaviate client instance.
batch_size : int
The batch size.
batch_target_rate : int
The batch target rate as # of objects per second.
"""

def callback(batch_results: dict) -> None:

# you could print batch errors here
time_took_to_create_batch = batch_size * (client.batch.creation_time/client.batch.recommended_num_objects)
time.sleep(
max(batch_size/batch_target_rate - time_took_to_create_batch + 1, 0)
)

client.batch.configure(
batch_size=batch_size,
timeout_retries=5,
callback=callback,
)

Usage example

This is an example of a nearText query with text2vec-aws.

import weaviate
import weaviate.classes as wvc
from weaviate.collections.classes.grpc import Move
import os

client = weaviate.connect_to_local(
headers={
"X-AWS-Access-Key": "YOUR_ACCESS_KEY",
"X-AWS-Secret-Key": "YOUR_SECRET_KEY",
}
)

publications = client.collections.get("Publication")

response = publications.query.near_text(
query="fashion",
distance=0.6,
move_to=Move(force=0.85, concepts="haute couture"),
move_away=Move(force=0.45, concepts="finance"),
return_metadata=wvc.query.MetadataQuery(distance=True),
limit=2
)

for o in response.objects:
print(o.properties)
print(o.metadata)

client.close()