Revision 1, checked Oct 18, 2026. Installs exactly voyageai 0.5.0, numpy 2.5.4, creates the files and adds the key names to your .env. It shows everything first and asks before changing anything.
A small Python script that turns six short documents and one question into Voyage embeddings, then prints the document that best answers the question. This is the core of semantic search and RAG.
Prerequisites
Python 3.9 or newer
A Voyage AI API key in VOYAGE_API_KEY (create it on the API keys page of the Voyage dashboard)
Steps
Install the packages:
Shell
pip install voyageai==0.5.0 numpy==2.5.4
Set your key (macOS/Linux):
Shell
export VOYAGE_API_KEY="<your secret key>"
Save this as search.py:
Python
import numpy as npimport voyageaivo = voyageai.Client()# This will automatically use the environment variable VOYAGE_API_KEY.# Alternatively, you can use vo = voyageai.Client(api_key="<your secret key>")documents = [ "The Mediterranean diet emphasizes fish, olive oil, and vegetables, believed to reduce chronic diseases.", "Photosynthesis in plants converts light energy into glucose and produces essential oxygen.", "20th-century innovations, from radios to smartphones, centered on electronic advancements.", "Rivers provide water, irrigation, and habitat for aquatic species, vital for ecosystems.", "Apple’s conference call to discuss fourth fiscal quarter results and business updates is scheduled for Thursday, November 2, 2023 at 2:00 p.m. PT / 5:00 p.m. ET.", "Shakespeare's works, like 'Hamlet' and 'A Midsummer Night's Dream,' endure in literature."]# Embed the documentsdocuments_embeddings = vo.embed( documents, model="voyage-4-large", input_type="document").embeddingsquery = "When is Apple's conference call scheduled?"# Get the embedding of the queryquery_embedding = vo.embed([query], model="voyage-4-large", input_type="query").embeddings[0]# Compute the similarity# Voyage embeddings are normalized to length 1, therefore dot-product and cosine# similarity are the same.similarities = np.dot(documents_embeddings, query_embedding)retrieved_id = np.argmax(similarities)print(documents[retrieved_id])
Test it
Run python search.py. It should print the Apple conference call sentence, since that is the document closest to the query.
Not confirmed
The official tutorial names the vectors doc_embds and query_embd in its similarity snippet but documents_embeddings and query_embedding earlier; this recipe uses the earlier names so the script runs as one file.
The docs install with pip install -U voyageai and use numpy without pinning it; the versions here are the latest on PyPI, not ones the docs name.
The docs only show the export command for macOS/Linux, not Windows.
The free allowance (first 200 million tokens for voyage-4-large, voyage-4 and voyage-4-lite) is from the pricing page and may change.
Wirestack