Text Embeddings
Weaviate's integration with AWS's SageMaker and Bedrock APIs allows you to access their models' capabilities directly from Weaviate.
Configure a Weaviate vector index to use an AWS embedding model, and Weaviate will generate embeddings for various operations using the specified model and your AWS API credentials. This feature is called the vectorizer.
At import time, Weaviate generates text object embeddings and saves them into the index. For vector and hybrid search operations, Weaviate converts text queries into embeddings.
Requirements
Section titled “Requirements”Weaviate configuration
Section titled “Weaviate configuration”Your Weaviate instance must be configured with the AWS vectorizer integration (text2vec-aws) module.
For Weaviate Cloud (WCD) users
This integration is enabled by default on Weaviate Cloud (WCD) instances.
For self-hosted users
- Check the cluster metadata to verify if the module is enabled.
- Follow the how-to configure modules guide to enable the module in Weaviate.
API credentials
Section titled “API credentials”You must provide access key based AWS credentials to Weaviate for these integrations. Go to AWS to sign up and obtain an AWS access key ID and a corresponding AWS secret access key.
Provide the API credentials to Weaviate using one of the following methods:
- Set the
AWS_ACCESS_KEYandAWS_SECRET_KEYenvironment variables that are available to Weaviate. - Provide the API credentials at runtime, as shown in the examples below.
# Recommended: save sensitive data as environment variables
aws_access_key = os.getenv("AWS_ACCESS_KEY")
aws_secret_key = os.getenv("AWS_SECRET_KEY")const aws_access_key = process.env.AWS_ACCESS_KEY || ''; // Replace with your AWS access key
const aws_secret_key = process.env.AWS_SECRET_KEY || ''; // Replace with your AWS secret key"X-AWS-Access-Key": os.Getenv("AWS_ACCESS_KEY"),
"X-AWS-Secret-Key": os.Getenv("AWS_SECRET_KEY"),AWS model access
Section titled “AWS model access”Bedrock
Section titled “Bedrock”To use a model via Bedrock, it must be available, and AWS must grant you access to it.
Refer to the AWS documentation for the list of available models, and to this document to find out how request access to a model.
SageMaker
Section titled “SageMaker”To use a model via SageMaker, you must have access to the model's endpoint.
Configure the vectorizer
Section titled “Configure the vectorizer”Configure a Weaviate index as follows to use an AWS embedding model.
The required parameters for the Bedrock and the SageMaker models are different.
Bedrock
Section titled “Bedrock”For Bedrock, you must provide the model name in the vectorizer configuration.
from weaviate.classes.config import Configureclient.collections.create( "DemoCollection", vector_config=[ Configure.Vectors.text2vec_aws( name="title_vector", region="us-east-1", source_properties=["title"], service="bedrock", model="amazon.titan-embed-text-v2:0", ) ], # Additional parameters not shown)await client.collections.create({ name: 'DemoCollection', properties: [ { name: 'title', dataType: 'text' as const, }, ], vectorizers: [ weaviate.configure.vectors.text2VecAWS({ name: 'title_vector', sourceProperties: ['title'], region: 'us-east-1', service: 'bedrock', // default service model: 'amazon.titan-embed-text-v1', }), ], // Additional parameters not shown});// Define the collectionbasicAWSBedrockVectorizerDef := &models.Class{ Class: "DemoCollection", VectorConfig: map[string]models.VectorConfig{ "title_vector": { Vectorizer: map[string]interface{}{ "text2vec-aws": map[string]interface{}{ "properties": []string{"title"}, "region": "us-east-1", "service": "bedrock", "model": "cohere.embed-multilingual-v3", }, }, }, },}// add the collectionerr = client.Schema().ClassCreator().WithClass(basicAWSBedrockVectorizerDef).Do(ctx)if err != nil { panic(err)}SageMaker
Section titled “SageMaker”For SageMaker, you must provide the endpoint address in the vectorizer configuration.
from weaviate.classes.config import Configureclient.collections.create( "DemoCollection", vector_config=[ Configure.Vectors.text2vec_aws( name="title_vector", region="us-east-1", source_properties=["title"], service="sagemaker", endpoint="<custom_sagemaker_name>", # e.g., "tei-xxx" ) ], # Additional parameters not shown)await client.collections.create({ name: 'DemoCollection', properties: [ { name: 'title', dataType: 'text' as const, }, ], vectorizers: [ weaviate.configure.vectors.text2VecAWS({ name: 'title_vector', sourceProperties: ['title'], region: 'us-east-1', service: 'sagemaker', model: '<custom_sagemaker_url>', }), ], // Additional parameters not shown});// Define the collectionbasicAWSSagemakerVectorizerDef := &models.Class{ Class: "DemoCollection", VectorConfig: map[string]models.VectorConfig{ "title_vector": { Vectorizer: map[string]interface{}{ "text2vec-aws": map[string]interface{}{ "properties": []string{"title"}, "region": "us-east-1", "service": "sagemaker", "endpoint": "<custom_sagemaker_url>", }, }, }, },}// add the collectionerr = client.Schema().ClassCreator().WithClass(basicAWSSagemakerVectorizerDef).Do(ctx)if err != nil { panic(err)}Vectorization behavior
Weaviate follows the collection configuration and a set of predetermined rules to vectorize objects.
Unless specified otherwise in the collection definition, the default behavior is to:
- Only vectorize properties that use the
textortext[]data type (unless skipped) - Sort properties in alphabetical (a-z) order before concatenating values
- If
vectorizePropertyNameistrue(falseby default) prepend the property name to each property value - Join the (prepended) property values with spaces
- Prepend the class name (unless
vectorizeClassNameisfalse) - Convert the produced string to lowercase
Vectorizer parameters
Section titled “Vectorizer parameters”Common parameters:
service(Optional): The AWS service to use, eitherbedrockorsagemaker. Defaults tobedrock.region(Required): The AWS region to send requests to, e.g.us-east-1.
Bedrock parameters:
model(Required): The full Bedrock model identifier, e.g.amazon.titan-embed-text-v2:0.dimensions(Optional): The size of the embedding to request from the model, e.g.512.
SageMaker parameters:
endpoint(Required): The name of the SageMaker endpoint to invoke, e.g.tei-xxx.targetModel(Optional): The model to target on a multi-model endpoint.targetVariant(Optional): The production variant to target on the endpoint.
service
Section titled “service”Weaviate falls back to bedrock when service is not set, so a SageMaker configuration has to set it to sagemaker. Any value other than bedrock or sagemaker is rejected when the collection is created.
Some clients offer service-specific constructors, such as text2vec_aws_bedrock and text2vec_aws_sagemaker, which select the service for you. Examples built on those constructors do not pass service at all. Every other example on this page sets it explicitly, as does any configuration written directly against the collection definition.
dimensions
Section titled “dimensions”dimensions was added in v1.36.19, and is also available from v1.37.10, v1.38.2, and v1.39.0 onward.
Weaviate only forwards dimensions to Amazon models on Bedrock, such as the Titan and Nova embedding families. Cohere models on Bedrock, and SageMaker endpoints, accept the setting in the collection configuration but ignore it when embeddings are generated, so their vectors keep the model's default size. Check the model's documentation for the sizes it supports.
Example configuration
Section titled “Example configuration”The following examples show how to configure AWS-specific options for each service.
from weaviate.classes.config import Configure# For Bedrockclient.collections.create( "DemoCollection", vector_config=[ Configure.Vectors.text2vec_aws_bedrock( name="title_vector", region="us-east-1", source_properties=["title"], model="amazon.titan-embed-text-v2:0", # Required # Further options # dimensions=512, # Amazon models only ) ], # Additional parameters not shown)# clean upclient.collections.delete("DemoCollection")# For SageMakerclient.collections.create( "DemoCollection", vector_config=[ Configure.Vectors.text2vec_aws_sagemaker( name="title_vector", region="us-east-1", source_properties=["title"], endpoint="<sagemaker_endpoint>", # Required # Further options # target_model="<sagemaker_target_model>", # target_variant="<sagemaker_target_variant>", ) ], # Additional parameters not shown)await client.collections.create({ name: 'DemoCollection', properties: [ { name: 'title', dataType: 'text' as const, }, ], vectorizers: [ weaviate.configure.vectors.text2VecAWS({ name: 'title_vector', sourceProperties: ['title'], region: 'us-east-1', service: 'bedrock', model: 'cohere.embed-multilingual-v3', // If using Bedrock // endpoint: '<custom_sagemaker_url>', // If using SageMaker // vectorizeClassName: true, }), ], // Additional parameters not shown});// Define the collectionawsVectorizerFullDef := &models.Class{ Class: "DemoCollection", VectorConfig: map[string]models.VectorConfig{ "title_vector": { Vectorizer: map[string]interface{}{ "text2vec-aws": map[string]interface{}{ "properties": []string{"title"}, "region": "us-east-1", "service": "bedrock", // "bedrock" or "sagemaker" "model": "cohere.embed-multilingual-v3", // If using `bedrock`, this is required // "endpoint": "<custom_sagemaker_url>", // If using `sagemaker`, this is required }, }, }, },}// add the collectionerr = client.Schema().ClassCreator().WithClass(awsVectorizerFullDef).Do(ctx)if err != nil { panic(err)}Data import
Section titled “Data import”After configuring the vectorizer, import data into Weaviate. Weaviate generates embeddings for text objects using the specified model.
source_objects = [ {"title": "The Shawshank Redemption", "description": "A wrongfully imprisoned man forms an inspiring friendship while finding hope and redemption in the darkest of places."}, {"title": "The Godfather", "description": "A powerful mafia family struggles to balance loyalty, power, and betrayal in this iconic crime saga."}, {"title": "The Dark Knight", "description": "Batman faces his greatest challenge as he battles the chaos unleashed by the Joker in Gotham City."}, {"title": "Jingle All the Way", "description": "A desperate father goes to hilarious lengths to secure the season's hottest toy for his son on Christmas Eve."}, {"title": "A Christmas Carol", "description": "A miserly old man is transformed after being visited by three ghosts on Christmas Eve in this timeless tale of redemption."}]collection = client.collections.use("DemoCollection")with collection.batch.fixed_size(batch_size=200) as batch: for src_obj in source_objects: # The model provider integration will automatically vectorize the object batch.add_object( properties={ "title": src_obj["title"], "description": src_obj["description"], }, # vector=vector # Optionally provide a pre-obtained vector ) if batch.number_errors > 10: print("Batch import stopped due to excessive errors.") breakfailed_objects = collection.batch.failed_objectsif failed_objects: print(f"Number of failed imports: {len(failed_objects)}") print(f"First failed object: {failed_objects[0]}")let srcObjects = [
{ title: "The Shawshank Redemption", description: "A wrongfully imprisoned man forms an inspiring friendship while finding hope and redemption in the darkest of places." },
{ title: "The Godfather", description: "A powerful mafia family struggles to balance loyalty, power, and betrayal in this iconic crime saga." },
{ title: "The Dark Knight", description: "Batman faces his greatest challenge as he battles the chaos unleashed by the Joker in Gotham City." },
{ title: "Jingle All the Way", description: "A desperate father goes to hilarious lengths to secure the season's hottest toy for his son on Christmas Eve." },
{ title: "A Christmas Carol", description: "A miserly old man is transformed after being visited by three ghosts on Christmas Eve in this timeless tale of redemption." }
];var sourceObjects = []map[string]string{ {"title": "The Shawshank Redemption", "description": "A wrongfully imprisoned man forms an inspiring friendship while finding hope and redemption in the darkest of places."}, {"title": "The Godfather", "description": "A powerful mafia family struggles to balance loyalty, power, and betrayal in this iconic crime saga."}, {"title": "The Dark Knight", "description": "Batman faces his greatest challenge as he battles the chaos unleashed by the Joker in Gotham City."}, {"title": "Jingle All the Way", "description": "A desperate father goes to hilarious lengths to secure the season's hottest toy for his son on Christmas Eve."}, {"title": "A Christmas Carol", "description": "A miserly old man is transformed after being visited by three ghosts on Christmas Eve in this timeless tale of redemption."},}// Convert items into a slice of models.Objectobjects := []models.PropertySchema{}for i := range sourceObjects { objects = append(objects, map[string]interface{}{ // Populate the object with the data "title": sourceObjects[i]["title"], "description": sourceObjects[i]["description"], })}// Batch write itemsbatcher := client.Batch().ObjectsBatcher()for _, dataObj := range objects { batcher.WithObjects(&models.Object{ Class: "DemoCollection", Properties: dataObj, })}// FlushbatchRes, err := batcher.Do(ctx)// Error handlingif err != nil { panic(err)}for _, res := range batchRes { if res.Result.Errors != nil { for _, err := range res.Result.Errors.Error { if err != nil { fmt.Printf("Error details: %v\n", *err) panic(err.Message) } } }}Searches
Section titled “Searches”Once the vectorizer is configured, Weaviate will perform vector and hybrid search operations using the specified AWS model.
Vector (near text) search
Section titled “Vector (near text) search”When you perform a vector search, Weaviate converts the text query into an embedding using the specified model and returns the most similar objects from the database.
The query below returns the n most similar objects from the database, set by limit.
collection = client.collections.use("DemoCollection")response = collection.query.near_text( query="A holiday film", # The model provider integration will automatically vectorize the query limit=2)for obj in response.objects: print(obj.properties["title"])const collectionName = 'DemoCollection'
const myCollection = client.collections.use(collectionName)nearTextResponse, err := client.GraphQL().Get(). WithClassName("DemoCollection"). WithFields( graphql.Field{Name: "title"}, ). WithNearText(client.GraphQL().NearTextArgBuilder(). WithConcepts([]string{"A holiday film"})). WithLimit(2). Do(ctx)if err != nil { panic(err)}fmt.Printf("%v", nearTextResponse)Hybrid search
Section titled “Hybrid search”When you perform a hybrid search, Weaviate converts the text query into an embedding using the specified model and returns the best scoring objects from the database.
The query below returns the n best scoring objects from the database, set by limit.
collection = client.collections.use("DemoCollection")response = collection.query.hybrid( query="A holiday film", # The model provider integration will automatically vectorize the query limit=2)for obj in response.objects: print(obj.properties["title"])const collectionName = 'DemoCollection'
const myCollection = client.collections.use(collectionName)hybridResponse, err := client.GraphQL().Get(). WithClassName("DemoCollection"). WithFields( graphql.Field{Name: "title"}, ). WithHybrid(client.GraphQL().HybridArgumentBuilder(). WithQuery("A holiday film")). WithLimit(2). Do(ctx)if err != nil { panic(err)}fmt.Printf("%v", hybridResponse)References
Section titled “References”Available models
Section titled “Available models”Bedrock
Section titled “Bedrock”amazon.titan-embed-text-v1amazon.titan-embed-text-v2:0cohere.embed-english-v3cohere.embed-multilingual-v3
Refer to this document to find out if the model is available in your region and how request access to a model.
SageMaker
Section titled “SageMaker”Any custom SageMaker name (e.g., "TEI-xxx") can be used as an endpoint.
Further resources
Section titled “Further resources”Other integrations
Section titled “Other integrations”Code examples
Section titled “Code examples”Once the integrations are configured at the collection, the data management and search operations in Weaviate work identically to any other collection. See the following model-agnostic examples:
- The How-to: Manage collections and How-to: Manage objects guides show how to perform data operations (i.e. create, read, update, delete collections and objects within them).
- The How-to: Query & Search guides show how to perform search operations (i.e. vector, keyword, hybrid) as well as retrieval augmented generation.
External resources
Section titled “External resources”Questions and feedback
Section titled “Questions and feedback”Have a question or feedback? Here's how to reach us.