Skip to main content

Build Your First RAG App with Vectorize

In this guide, you'll build a working Retrieval-Augmented Generation (RAG) pipeline using the Vectorize API. You'll upload documents, create a retrieval pipeline, and run your first structured query — all using live, production-ready code examples.

What You'll Build​

By the end of this guide, you'll have:

  • A working RAG pipeline that processes your documents
  • A retrieval endpoint that can answer questions about your uploaded content
  • Familiarity with core Vectorize concepts

Prerequisites

Before you begin, you'll need:

  1. A Vectorize account
  2. An API access token (how to create one)
  3. Your organization ID (see below)

Finding your Organization ID

Your organization ID is in the Vectorize platform URL:

https://platform.vectorize.io/organization/[YOUR-ORG-ID]

For example, if your URL is:

https://platform.vectorize.io/organization/ecf3fa1d-30d0-4df1-8af6-f4852bc851cb

Your organization ID is: ecf3fa1d-30d0-4df1-8af6-f4852bc851cb

API Client Setup

import vectorize_client as v
import os

# Get credentials from environment variables
organization_id = "your-org-id"
api_key = "your-api-key"

if not organization_id or not api_key:
    raise ValueError("Please set VECTORIZE_ORGANIZATION_ID and VECTORIZE_API_KEY environment variables")

# Initialize the API client
configuration = v.Configuration(
    host="https://api.vectorize.io",
    api_key={"ApiKeyAuth": api_key}
)
api = v.ApiClient(configuration)

print(f"✅ API client initialized for organization: {"your-org-id"}")

What is RAG?​

Retrieval-Augmented Generation (RAG) combines large language models with your own data. Instead of relying on an AI's general knowledge, RAG:

  1. Stores your documents in a searchable format
  2. Retrieves relevant information when asked a question
  3. Generates answers using your specific content

Step 1: Create a File Upload Connector​

A connector is how you get data into Vectorize. For this guide, we'll use a File Upload connector to upload documents directly:

# Create the connectors API client
connectors_api = v.SourceConnectorsApi(api)

try:
    # Create a file upload connector
    file_upload = v.FileUpload(
        name="my-document-upload",
        type="FILE_UPLOAD",
        config={}
    )

    request = v.CreateSourceConnectorRequest(file_upload)
    response = connectors_api.create_source_connector(
        organization_id,
        request
    )

    connector_id = response.connector.id
    print(f"✅ Created file upload connector: {connector_id}")

except Exception as e:
    print(f"❌ Error creating connector: {e}")
    raise

Step 2: Upload Your First Document​

Now let's upload a document. In this example, we’re uploading a simple .txt file for clarity. You can upload PDFs, Word docs, or any supported text format — the upload process is the same regardless of file type.

import urllib3

# Create uploads API client
uploads_api = v.UploadsApi(api)

try:
    # Step 1: Get upload URL
    upload_request = v.StartFileUploadToConnectorRequest(
        name=file_name,
        content_type="text/plain"
    )

    start_response = uploads_api.start_file_upload_to_connector(
        organization_id,
        source_connector_id,
        start_file_upload_to_connector_request=upload_request
    )

    # Step 2: Upload file to the URL
    http = urllib3.PoolManager()
    with open(file_path, "rb") as f:
        response = http.request(
            "PUT",
            start_response.upload_url,
            body=f,
            headers={
                "Content-Type": "text/plain",
                "Content-Length": str(os.path.getsize(file_path))
            }
        )

    if response.status == 200:
        print(f"✅ Successfully uploaded: {file_name}")
    else:
        print(f"❌ Upload failed: {response.status}")

except Exception as e:
    print(f"❌ Error uploading file: {e}")
    raise

Step 3: Create Your RAG Pipeline​

A pipeline connects your data source (the File Upload connector) to AI processing and storage. Vectorize provides built-in AI and vector storage to get you started quickly:

# Create pipelines API client
pipelines_api = v.PipelinesApi(api)

try:
    # Configure your pipeline
    pipeline_config = v.PipelineConfigurationSchema(
        pipeline_name="My First RAG Pipeline",
        source_connectors=[
            v.PipelineSourceConnectorSchema(
                id=source_connector_id,
                type="FILE_UPLOAD",
                config={}
            )
        ],
        ai_platform_connector=v.PipelineAIPlatformConnectorSchema(
            id=ai_platform_connector_id,  # Uses Vectorize's built-in AI
            type="VECTORIZE",
            config={}
        ),
        destination_connector=v.PipelineDestinationConnectorSchema(
            id=destination_connector_id,  # Uses Vectorize's built-in vector store
            type="VECTORIZE",
            config={}
        ),
        schedule=v.ScheduleSchema(type="manual")
    )

    # Create the pipeline
    response = pipelines_api.create_pipeline(
        organization_id,
        pipeline_config
    )

    pipeline_id = response.data.id
    print(f"✅ Created pipeline: {pipeline_id}")

except Exception as e:
    print(f"❌ Error creating pipeline: {e}")
    raise

What's Happening Here?​

When you create a pipeline:

  1. Source Connector: Specifies where documents come from
  2. AI Platform Connector: Processes and understands your documents (Vectorize's built-in AI)
  3. Destination Connector: Stores processed documents for fast retrieval (Vectorize's vector store)
  4. Schedule: When to check for new documents (manual = on-demand)

Step 4: Wait for Processing​

Your pipeline needs a few moments to process the uploaded document. Let's monitor its progress:

# Create pipelines API client
pipelines_api = v.PipelinesApi(api)

print("Waiting for pipeline to process your document...")
max_wait_time = 300  # 5 minutes
start_time = time.time()

while True:
    try:
        # Check pipeline status
        pipeline = pipelines_api.get_pipeline(organization_id, pipeline_id)

        status = pipeline.data.status

        # Check if ready
        if status == "LISTENING":
            print("✅ Pipeline is ready!")
            break
        elif status == "PROCESSING":
            print("⚙️  Still processing...")
        elif status in ["ERROR_DEPLOYING", "SHUTDOWN"]:
            print(f"❌ Pipeline error: {status}")
            break

        # Check timeout
        if time.time() - start_time > max_wait_time:
            print("⏰ Timeout waiting for pipeline")
            break

        time.sleep(10)  # Check every 10 seconds

    except Exception as e:
        print(f"❌ Error checking status: {e}")
        break

Pipeline States​

  • DEPLOYING: Pipeline is being set up
  • PROCESSING: Actively processing documents
  • LISTENING: Ready and waiting for queries

For a complete list of pipeline states, see Understanding Pipeline Status.

Step 5: Query Your RAG Pipeline​

Once the pipeline is ready, you can query it:

# Create pipelines API client
pipelines_api = v.PipelinesApi(api)

try:
    # Query the pipeline
    response = pipelines_api.retrieve_documents(
        organization_id,
        pipeline_id,
        v.RetrieveDocumentsRequest(
            question="How to call the API?",
            num_results=5
        )
    )

    # Display results
    print(f"Found {len(response.documents)} relevant documents:\n")
    for i, doc in enumerate(response.documents, 1):
        print(f"Result {i}:")
        print(f"  Content: {doc.text[:200]}...")  # Use 'text' instead of 'content'
        print(f"  Relevance Score: {doc.relevancy}")  # Use 'relevancy' instead of 'score'
        print(f"  Document ID: {doc.id}")
        print()

except Exception as e:
    print(f"❌ Error querying pipeline: {e}")
    raise

How Queries Work​

When you submit a query:

  1. Your question is converted to a vector (mathematical representation)
  2. Vectorize finds the most relevant chunks from your documents
  3. These chunks are sent to the AI as context
  4. The AI generates an answer based on your specific content

Understanding Your Results​

The query response includes:

  • Answer: The AI-generated response to your question
  • Sources: Which document chunks were used
  • Confidence: How relevant the retrieved content was
  • Metadata: Additional information about the sources

Try the Interactive Chatbot​

For quick testing, Vectorize provides an interactive chatbot for each pipeline. You can access it at:

https://platform.vectorize.io/pipelines/[your-pipeline-id]/chat

This uses the same retrieval endpoint you've just configured. It’s useful for:

  • Testing your pipeline quickly
  • Sharing with non-technical users
  • Demonstrating your RAG application

What's Next?​

Congratulations! You've built your first RAG application with Vectorize.

Here are some next steps to explore:

When you're ready to add structured metadata and filtering to your pipeline, try defining a schema using the Visual Schema Editor or API.

Was this page helpful?