Skip to main content

​
Voyage AI + Moorcheh

This integration uses the Voyage AI Python client to generate embeddings and Moorcheh vector namespaces to store and search them with ITS ranking. The example below uses voyage-4 (default 1024 dimensions; other sizes and models are described in the Voyage embeddings docs).

​
Architecture

Embedding generation

voyageai.Client.embed() with input_type="document" or "query" for retrieval

Vector storage

Store vectors in Moorcheh vector namespaces

Semantic retrieval

Same model and dimension settings for indexed chunks and queries

Authentication

VOYAGE_API_KEY — see API key setup

​
Prerequisites

pip install voyageai moorcheh-sdk python-dotenv
The PyPI package is voyageai. If you see ModuleNotFoundError: No module named 'voyageai', run the install line above with the same Python you use to run your script.

​
.env file

MOORCHEH_API_KEY=your_moorcheh_key
VOYAGE_API_KEY=your_voyage_key

​
Model and dimensions

This example uses voyage-4 with the default 1024-dimensional float embeddings. Set Moorcheh vector_dimension to match. You can switch to another supported model (for example voyage-4-lite, voyage-3.5) and optional output_dimension — keep index and query settings aligned. For retrieval, pass input_type="document" when embedding stored chunks and input_type="query" when embedding the search query.

​
End-to-end example

import os
import textwrap
from typing import List

import voyageai
from dotenv import load_dotenv
from moorcheh_sdk import MoorchehClient

load_dotenv()

MOORCHEH_API_KEY = os.getenv("MOORCHEH_API_KEY", "").strip()
VOYAGE_API_KEY = os.getenv("VOYAGE_API_KEY", "").strip()
if not MOORCHEH_API_KEY or not VOYAGE_API_KEY:
    raise SystemExit("Set MOORCHEH_API_KEY and VOYAGE_API_KEY.")

MODEL = "voyage-4"
VECTOR_DIMENSION = 1024
NAMESPACE = "voyage-embed-demo"
CHUNK_SIZE = 900
CHUNK_OVERLAP = 180


def to_float_vector(values: List[float]) -> List[float]:
    return [float(x) for x in values]


def chunk_text(text: str, chunk_size: int = CHUNK_SIZE, overlap: int = CHUNK_OVERLAP) -> List[str]:
    chunks: List[str] = []
    start = 0
    while start < len(text):
        end = min(start + chunk_size, len(text))
        chunks.append(text[start:end].strip())
        if end == len(text):
            break
        start = max(end - overlap, 0)
    return [c for c in chunks if c]


def extract_text(result: dict) -> str:
    if result.get("text"):
        return str(result["text"])
    metadata = result.get("metadata") or {}
    if isinstance(metadata, dict):
        return str(metadata.get("text") or metadata.get("raw_text") or metadata.get("content") or "")
    return ""


def clean_text(text: str) -> str:
    return " ".join(str(text).split())


def print_result(idx: int, result: dict) -> None:
    metadata = result.get("metadata") or {}
    text_value = clean_text(extract_text(result))
    wrapped = textwrap.fill(text_value, width=100)
    print(f"[{idx}] id={result.get('id')}")
    print(f"score={result.get('score')} label={result.get('label')}")
    print(f"section={metadata.get('section')} source_doc_id={metadata.get('source_doc_id')}")
    print("text:")
    print(wrapped if wrapped else "(no text returned)")
    print("-" * 120)


vo = voyageai.Client(api_key=VOYAGE_API_KEY)
mc = MoorchehClient(api_key=MOORCHEH_API_KEY)

try:
    mc.namespaces.create(
        namespace_name=NAMESPACE,
        type="vector",
        vector_dimension=VECTOR_DIMENSION,
    )
except Exception:
    pass

source_documents = [
    {
        "id": "guide-vector-namespaces",
        "section": "vector-namespace-best-practices",
        "text": (
            "Moorcheh vector namespaces support bring-your-own-embedding workflows. "
            "Use Voyage with input_type document for chunks and query for search strings; match vector_dimension to the embedding size."
        ),
    },
    {
        "id": "guide-search-tuning",
        "section": "semantic-search-tuning",
        "text": (
            "Tune similarity_search top_k and threshold for your use case."
        ),
    },
]

documents = []
for doc in source_documents:
    parts = chunk_text(doc["text"])
    for idx, chunk in enumerate(parts):
        documents.append(
            {
                "id": f"{doc['id']}-chunk-{idx}",
                "text": chunk,
                "source_doc_id": doc["id"],
                "section": doc["section"],
                "chunk_index": idx,
                "total_chunks": len(parts),
            }
        )

texts = [d["text"] for d in documents]
doc_result = vo.embed(texts, model=MODEL, input_type="document")

mc.vectors.upload(
    namespace_name=NAMESPACE,
    vectors=[
        {
            "id": documents[i]["id"],
            "vector": to_float_vector(doc_result.embeddings[i]),
            "text": documents[i]["text"],
            "source": "voyage",
            "model": MODEL,
            "section": documents[i]["section"],
            "source_doc_id": documents[i]["source_doc_id"],
            "chunk_index": documents[i]["chunk_index"],
            "total_chunks": documents[i]["total_chunks"],
        }
        for i in range(len(documents))
    ],
)

query = "How do I use Voyage input_type with Moorcheh?"
q_result = vo.embed([query], model=MODEL, input_type="query")
query_vec = to_float_vector(q_result.embeddings[0])

results = mc.similarity_search.query(
    namespaces=[NAMESPACE],
    query=query_vec,
    top_k=5,
    kiosk_mode=True,
    threshold=0.15,
)

print(f"namespace={NAMESPACE} total_results={len(results.get('results', []))}")
print("=" * 120)
for idx, r in enumerate(results.get("results", []), start=1):
    print_result(idx, r)

​
Runnable demo script

See integrations/voyage/voyage_moorcheh_demo.py.

​
Important notes

Default for voyage-4 at default settings is 1024. If you change output_dimension or model, recreate or align the namespace dimension.
For retrieval, use input_type="document" for indexed text and input_type="query" for the query string.
Include text on each uploaded vector so search results can return the original chunk.