You can integrate MongoDB with Fireworks AI to build retrieval-augmented generation (RAG) applications on open-source models. This tutorial uses Voyage AI to embed and rerank sample data, and then uses a Fireworks chat model to generate a grounded recommendation.
In this tutorial, you perform the following tasks:
Set up your environment.
Use a Voyage AI embedding model to embed movie data and store the embeddings in MongoDB.
Use MongoDB Vector Search and a Voyage AI reranker model to retrieve and rerank movie documents.
Instruct a Fireworks chat model to generate a movie recommendation based on the reranked results.
Background
Fireworks AI provides a platform for training and running open-source AI models. You can use MongoDB to store operational and memory data, and to retrain models for specific use cases.
A RAG application retrieves relevant data and passes it to a chat model as context, so the model answers from your data instead of relying only on what it learned during training. In this tutorial, MongoDB stores and retrieves your data. Voyage AI provides the embedding model that embeds the data and the reranker model that reranks the retrieved results, and Fireworks AI provides the chat model that generates the final response.
Prerequisites
To complete this tutorial, you must have the following resources:
One of the following MongoDB cluster types:
An Atlas cluster running MongoDB version 6.0.11, 7.0.2, or later. Ensure that your IP address is included in your Atlas project's access list.
A local Atlas deployment created using Python and Docker. Install
atlas-local-lib-py(pip install atlas-local-lib-py) to programmatically create and manage local deployments. To learn more, see the atlas-local-lib-py repository.A MongoDB Community cluster with Search and Vector Search installed.
The sample dataset loaded into your cluster. This tutorial uses the
sample_mflix.moviescollection.A Fireworks AI API key. To create one, go to API Keys in your Fireworks account settings.
A Voyage AI API key. To create one, see Manage Voyage AI Model API Keys.
Python v3.11 or later.
Set Up the Environment
In this section, you prepare your environment by creating a virtual environment, installing the required dependencies, setting your environment variables, and creating a project file.
Set your environment variables.
In your fireworks-mongodb-project directory, create a .env file and add the following code:
FIREWORKS_API_KEY="<fireworks-api-key>"VOYAGE_API_KEY="<voyage-api-key>"MONGODB_URI="<connection-string>"Replace <fireworks-api-key> with your Fireworks API key, and replace <voyage-api-key> with your Voyage AI API key.
Replace <connection-string> with the connection string for your Atlas cluster or local Atlas deployment.
Your connection string should use the following format:
mongodb+srv://<db_username>:<db_password>@<clusterName>.<hostname>.mongodb.netIMPORTANT: Ensure that your connection string includes your database user's credentials. To learn more about finding your connection string, see Connect to a Cluster via Client Libraries.
Your connection string should use the following format:
mongodb://localhost:<port-number>/?directConnection=trueTo learn more, see Connection Strings.
Create a project file.
In your fireworks-mongodb-project directory, create a file named main.py. Add the following code to this file to load your environment variables and define two command-line arguments, which specify the search query and the number of results:
import argparseimport osimport time
import voyageaifrom dotenv import load_dotenvfrom openai import OpenAIfrom pymongo import MongoClientfrom pymongo.operations import SearchIndexModel
load_dotenv()
parser = argparse.ArgumentParser()parser.add_argument("--query", default="something interesting")parser.add_argument("--count", type=int, default=10)args = parser.parse_args()In future steps, you add code to this file to embed, retrieve, and generate responses from your movie data.
Embed and Store Movie Data
In this section, you set up your clients, embed the plot field of 50 movie documents, and store each vector in a new embedding field. Then, you create a MongoDB Vector Search index on that field.
Create the required clients.
Add the following code to your main.py file to create a Fireworks client, a Voyage AI client, and a MongoDB client, and to select your models:
fireworks = OpenAI( base_url="https://api.fireworks.ai/inference/v1", api_key=os.environ["FIREWORKS_API_KEY"],)voyage = voyageai.Client()
mongo_client = MongoClient(os.environ["MONGODB_URI"])collection = mongo_client["sample_mflix"]["movies"]
EMBEDDING_MODEL = "voyage-4"RERANK_MODEL = "rerank-3"CHAT_MODEL = "accounts/fireworks/models/gpt-oss-120b"DIMENSIONS = 1024This example selects the following models:
voyage-4: A Voyage AI embedding model, used to embed movie plots and search queries.rerank-3: A Voyage AI reranker model, used to rescore MongoDB Vector Search candidates for relevance.accounts/fireworks/models/gpt-oss-120b: A Fireworks chat model, used to generate movie recommendations based on MongoDB data.
Note
This tutorial requests 1024-dimension vectors from the Voyage AI embedding model to reduce storage. You can use any Voyage AI embedding model, as long as the DIMENSIONS value matches the size of the vectors that the model returns.
Generate and store embeddings.
Add the following code to your main.py file to embed each movie's plot in the embedding field:
def get_embeddings(texts, input_type="document"): response = voyage.embed( texts, model=EMBEDDING_MODEL, input_type=input_type, output_dimension=DIMENSIONS ) return response.embeddings
docs = list( collection.find( {"plot": {"$exists": True, "$ne": ""}}, {"_id": 1, "title": 1, "plot": 1} ).limit(50))
vectors = get_embeddings([doc["plot"] for doc in docs])
for doc, vector in zip(docs, vectors): collection.update_one({"_id": doc["_id"]}, {"$set": {"embedding": vector}})
print(f"Embedded {len(docs)} movies.")Create the MongoDB Vector Search index.
Add the following code to create a MongoDB Vector Search index on the embedding field and wait until the index finishes building:
index = SearchIndexModel( definition={ "fields": [ { "type": "vector", "path": "embedding", "numDimensions": DIMENSIONS, "similarity": "cosine", } ] }, name="movie_vector_index", type="vectorSearch",)collection.create_search_index(model=index)
print("Waiting for the index to build...")while not any( idx.get("queryable") for idx in collection.list_search_indexes("movie_vector_index")): time.sleep(5)
print("Index is ready.")Generate a Response from Vector Search Results
In this section, you run a MongoDB Vector Search query on the documents' plot field and rerank the results. Then, you pass the reranked movies to a Fireworks chat model as context to generate a recommendation.
Run a MongoDB Vector Search query.
Add the following code to your main.py file to embed a plot field query and retrieve movies whose plots are similar to the query:
def vector_search(query, limit=5): query_vector = get_embeddings([query], input_type="query")[0] pipeline = [ { "$vectorSearch": { "index": "movie_vector_index", "path": "embedding", "queryVector": query_vector, "numCandidates": limit * 20, "limit": limit, } }, { "$project": { "_id": 0, "title": 1, "plot": 1, "score": {"$meta": "vectorSearchScore"}, } }, ] return list(collection.aggregate(pipeline))
print("\nVector search results:")for movie in vector_search(args.query, limit=args.count): print(f'{movie["score"]:.3f} {movie["title"]}')Rerank the results.
To improve MongoDB Vector Search precision, retrieve a larger candidate set and rerank it by using a Voyage AI reranker model before you pass the results to a chat model. Add the following code to your main.py file:
def rerank(query, movies, top_n=5): candidate_texts = [f'{m["title"]}: {m["plot"]}' for m in movies] reranking = voyage.rerank(query, candidate_texts, model=RERANK_MODEL, top_k=top_n) return [movies[result.index] for result in reranking.results]
def retrieve(query, top_n=5): return rerank(query, vector_search(query, limit=top_n * 4), top_n=top_n)
print("\nReranked, precise results:")for movie in retrieve(args.query, top_n=args.count): print(movie["title"])Generate a response.
Add the following code to your main.py file to pass the reranked movies to a Fireworks chat model as context, and instruct the model to answer only from that context:
def answer(question): context = "\n\n".join(f'{m["title"]}: {m["plot"]}' for m in retrieve(question)) response = fireworks.chat.completions.create( model=CHAT_MODEL, messages=[ { "role": "system", "content": "Answer using only the movies in the context. " "If the context doesn't contain the answer, say so.", }, { "role": "user", "content": f"Context:\n{context}\n\nQuestion: {question}", }, ], ) return response.choices[0].message.content
print("\nRecommendation:")print(answer(f"Recommend a movie about {args.query}, and explain why."))Run the File
To run the main.py file, run the following command from your fireworks-mongodb-project directory. Use the --query and --count flags to specify the search query and the number of results that the file returns:
uv run main.py --query "a heist that goes wrong" --count 5If the command runs successfully, the output resembles the following:
Embedded 50 movies.Waiting for the index to build...Index is ready.
Vector search results:0.724 I Became a Criminal0.664 Hallelujah0.662 Zoo in Budapest0.658 Rear Window0.654 The Long Voyage Home
Reranked, precise results:I Became a CriminalHallelujahFoolish WivesZoo in BudapestA Corner in Wheat
Recommendation:**I Became a Criminal** -- This gritty film-noir follows cynicalex-RAF flyer Morgan, who joins a break-in gang led by Narcy. Theirfirst job quickly turns disastrous when the getaway car crashesafter the crew accidentally kills a policeman. The movie centers ona heist that goes badly wrong, showcasing the chaos, moral fallout,and gritty consequences of a botched robbery.Next Steps
To learn more about the Fireworks and Voyage AI configuration options and the methods used in this tutorial, see Integrate MongoDB with Fireworks AI.
To build a tool-calling agent that remembers its conversation history in MongoDB, see Specify Agent Tools and Persist Agent Memory.
To learn more about Fireworks AI, see the Fireworks AI Documentation.
To learn more about Voyage AI, see Text Embeddings and Rerankers.