> ## Documentation Index
> Fetch the complete documentation index at: https://masaic-ai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Enhance AI responses with relevant information from your document collections

The RAG system provides a comprehensive solution for enhancing your AI model outputs with relevant information from your document collections. This powerful capability enables more accurate, informative, and contextually relevant responses.

## System Overview

The RAG system exposes several APIs that you can use in your applications:

<CardGroup cols={4}>
  <Card title="Files API" icon="file" href="/rag/files-api">
    Upload, manage, and retrieve documents
  </Card>

  <Card title="Vector Store API" icon="database" href="/rag/vectorstore-api">
    Create and manage collections of document embeddings
  </Card>

  <Card title="Search API" icon="magnifying-glass" href="/rag/search-api">
    Perform semantic search across your document collections
  </Card>

  <Card title="Embedding Models" icon="microchip" href="/rag/embedding">
    Configure embedding models for vector representations
  </Card>
</CardGroup>

<div className="my-6 overflow-auto max-w-full">
  <Frame caption="RAG System API Overview">
    <table className="w-full text-sm" style={{ borderCollapse: "separate", borderRadius: "4px", overflow: "hidden" }}>
      <thead>
        <tr className="bg-gray-200 dark:bg-gray-800">
          <th className="border border-gray-300 p-2" style={{ borderTopLeftRadius: "4px" }}>Feature</th>
          <th className="border border-gray-300 p-2">Files API</th>
          <th className="border border-gray-300 p-2">Vector Store API</th>
          <th className="border border-gray-300 p-2" style={{ borderTopRightRadius: "4px" }}>Search API</th>
        </tr>
      </thead>

      <tbody>
        <tr>
          <td className="border border-gray-300 p-2 font-medium">Purpose</td>
          <td className="border border-gray-300 p-2">Document management</td>
          <td className="border border-gray-300 p-2">Embedding storage</td>
          <td className="border border-gray-300 p-2">Content retrieval</td>
        </tr>

        <tr className="bg-gray-100 dark:bg-gray-700">
          <td className="border border-gray-300 p-2 font-medium">Endpoints</td>
          <td className="border border-gray-300 p-2"><code>/v1/files</code></td>
          <td className="border border-gray-300 p-2"><code>/v1/vector\_stores</code></td>
          <td className="border border-gray-300 p-2"><code>/v1/vector\_stores/:id/search</code></td>
        </tr>

        <tr>
          <td className="border border-gray-300 p-2 font-medium">Input</td>
          <td className="border border-gray-300 p-2">PDF, TXT, etc.</td>
          <td className="border border-gray-300 p-2">File IDs</td>
          <td className="border border-gray-300 p-2">Query, filters</td>
        </tr>

        <tr className="bg-gray-100 dark:bg-gray-700">
          <td className="border border-gray-300 p-2 font-medium" style={{ borderBottomLeftRadius: "4px" }}>Output</td>
          <td className="border border-gray-300 p-2">File metadata</td>
          <td className="border border-gray-300 p-2">Store metadata</td>
          <td className="border border-gray-300 p-2" style={{ borderBottomRightRadius: "4px" }}>Content chunks</td>
        </tr>
      </tbody>
    </table>
  </Frame>
</div>

### How RAG Works

1. You upload documents via the Files API
2. You add these documents to vector stores using the Vector Store API
3. The system automatically processes documents, extracting and embedding their content
4. Your application or AI assistants query for relevant information using the Search API
5. You enhance AI responses with the retrieved information

<div className="my-8 overflow-auto">
  <Frame caption="Detailed RAG API Data Flow">
    <div style={{ minWidth: "600px" }}>
      ```mermaid theme={null}
      %%{init: {'theme': 'neutral', 'themeVariables': {'primaryColor': '#f0f0f0', 'primaryTextColor': '#333', 'primaryBorderColor': '#666', 'lineColor': '#555', 'secondaryColor': '#e6e6e6', 'tertiaryColor': '#d9d9d9', 'linkColor': '#ffffff', 'edgeLabelBackground': '#333333'}}}%%
      sequenceDiagram
        actor User
        participant FA as Files API
        participant VS as Vector Store API
        participant S as Search API
        participant AI as AI Model
        
        Note over User,AI: 1. Document Upload
        User->>FA: Upload document
        FA-->>User: Return file ID
        
        Note over User,AI: 2. Vector Store Creation
        User->>VS: Create vector store
        VS-->>User: Return store ID
        
        Note over User,AI: 3. File Processing
        User->>VS: Add file to store
        VS-->>User: Processing status
        Note over VS: System embeds document
        
        Note over User,AI: 4. Search
        User->>S: Query with filters
        S-->>User: Relevant content
        
        Note over User,AI: 5. AI Enhancement
        User->>AI: Query with file_search tool
        AI->>S: Internal search
        S-->>AI: Document context
        AI-->>User: Enhanced response
      ```
    </div>
  </Frame>
</div>

## Getting Started

### Prerequisites

* LLM provider's API key for authentication
* Access to the Open Responses API endpoints
* Documents you want to make searchable

## Step-by-Step Integration Guide

### 1. Configure Your Environment

Set up your environment variables:

```bash theme={null}
# For OpenAI integration
export OPENAI_API_KEY=your_openai_api_key

# For Groq integration
export GROQ_API_KEY=your_groq_api_key

# For embedding configuration (optional)
export OPEN_RESPONSES_EMBEDDINGS_HTTP_ENABLED=true
export OPEN_RESPONSES_EMBEDDINGS_API_KEY=your_openai_api_key
export OPEN_RESPONSES_EMBEDDINGS_MODEL=text-embedding-3-small
```

<Tip>
  For detailed embedding configuration options, see the [Embedding Models](/rag/embedding) documentation.
</Tip>

### 2. Upload Documents

Upload documents using the Files API:

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'http://localhost:6644/v1/files' \
  --header 'Authorization: Bearer $YOUR_API_KEY' \
  --form 'file=@"/path/to/your/document.pdf"' \
  --form 'purpose="user_data"'
  ```

  ```python Python theme={null}
  import requests

  url = "http://localhost:6644/v1/files"
  headers = {
      "Authorization": f"Bearer {your_api_key}"
  }
  files = {
      "file": open("/path/to/your/document.pdf", "rb")
  }
  data = {
      "purpose": "user_data"
  }

  response = requests.post(url, headers=headers, files=files, data=data)
  print(response.json())
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "id": "file_abc123",
  "object": "file",
  "bytes": 12345,
  "created_at": 1677610602,
  "filename": "document.pdf",
  "purpose": "user_data"
}
```

### 3. Create a Vector Store

Create a vector store to hold document embeddings:

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'http://localhost:6644/v1/vector_stores' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_API_KEY' \
  --data '{
    "name": "My Knowledge Base"
  }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "http://localhost:6644/v1/vector_stores"
  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Bearer {your_api_key}"
  }
  payload = {
      "name": "My Knowledge Base"
  }

  response = requests.post(url, headers=headers, data=json.dumps(payload))
  print(response.json())
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "id": "vs_def456",
  "object": "vector_store",
  "created_at": 1677610602,
  "name": "My Knowledge Base",
  "file_count": 0,
  "metadata": {}
}
```

### 4. Add Files to the Vector Store

Add your uploaded files to the vector store:

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'http://localhost:6644/v1/vector_stores/vs_def456/files' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_API_KEY' \
  --data '{
    "file_id": "file_abc123",
    "chunking_strategy": {
      "type": "static",
      "static": {
        "max_chunk_size_tokens": 1000,
        "chunk_overlap_tokens": 200
      }
    },
    "attributes": {
      "category": "documentation",
      "language": "en"
    }
  }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "http://localhost:6644/v1/vector_stores/vs_def456/files"
  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Bearer {your_api_key}"
  }
  payload = {
      "file_id": "file_abc123",
      "chunking_strategy": {
          "type": "static",
          "static": {
              "max_chunk_size_tokens": 1000,
              "chunk_overlap_tokens": 200
          }
      },
      "attributes": {
          "category": "documentation",
          "language": "en"
      }
  }

  response = requests.post(url, headers=headers, data=json.dumps(payload))
  print(response.json())
  ```
</CodeGroup>

Response:

```json theme={null}
{
  "id": "vsfile_ghi789",
  "object": "vector_store.file",
  "created_at": 1677610603,
  "vector_store_id": "vs_def456",
  "status": "processing",
  "usage_bytes": 0,
  "chunking_strategy": {
    "type": "static",
    "static": {
      "max_chunk_size_tokens": 1000,
      "chunk_overlap_tokens": 200
    }
  },
  "attributes": {
    "category": "documentation",
    "language": "en"
  }
}
```

### 5. Search the Vector Store

Search for relevant content:

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'http://localhost:6644/v1/vector_stores/vs_def456/search' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $YOUR_API_KEY' \
  --data '{
    "query": "How do I configure the system?",
    "max_num_results": 5,
    "filters": {
      "type": "eq",
      "key": "language",
      "value": "en"
    }
  }'
  ```

  ```python Python theme={null}
  import requests
  import json

  url = "http://localhost:6644/v1/vector_stores/vs_def456/search"
  headers = {
      "Content-Type": "application/json",
      "Authorization": f"Bearer {your_api_key}"
  }
  payload = {
      "query": "How do I configure the system?",
      "max_num_results": 5,
      "filters": {
          "type": "eq",
          "key": "language",
          "value": "en"
      }
  }

  response = requests.post(url, headers=headers, data=json.dumps(payload))
  print(response.json())
  ```
</CodeGroup>

## Integration with AI Models

### Using the file\_search Tool with OpenAI

You can integrate RAG with OpenAI models by using the `file_search` tool:

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'http://localhost:6644/v1/responses' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer $OPENAI_API_KEY' \
  --data '{
      "model": "openai@gpt-4o",
      "store": true,
      "tools": [{
        "type": "file_search",
        "vector_store_ids": ["vs_def456"],
        "max_num_results": 5,
        "filters": {
          "type": "and",
          "filters": [
            {
              "type": "eq",
              "key": "language",
              "value": "en"
            },
            {
              "type": "eq",
              "key": "category",
              "value": "documentation"
            }
          ]
        }
      }],
      "input": "How do I configure the system?",
      "instructions": "Answer questions using information from the provided documents.",
      "stream": false
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      base_url="http://localhost:6644/v1",
      api_key="your_openai_api_key"
  )

  response = client.responses.create(
      model="openai@gpt-4o",
      store=True,
      tools=[{
          "type": "file_search",
          "vector_store_ids": ["vs_def456"],
          "max_num_results": 5,
          "filters": {
              "type": "and",
              "filters": [
                  {
                      "type": "eq",
                      "key": "language",
                      "value": "en"
                  },
                  {
                      "type": "eq",
                      "key": "category",
                      "value": "documentation"
                  }
              ]
          }
      }],
      "input": "How do I configure the system?",
      "instructions": "Answer questions using information from the provided documents.",
      "stream": False
  )

  print(response)
  ```
</CodeGroup>

## Advanced Usage

### Chunking Strategies

When adding files to a vector store, you can specify how the documents should be chunked:

```json theme={null}
"chunking_strategy": {
  "type": "static",
  "static": {
    "max_chunk_size_tokens": 1000,
    "chunk_overlap_tokens": 200
  }
}
```

<div className="my-6 overflow-auto">
  <Frame caption="Document Chunking and Embedding Process">
    <div style={{ minWidth: "500px" }}>
      ```mermaid theme={null}
      %%{init: {'theme': 'neutral', 'themeVariables': {'primaryColor': '#f0f0f0', 'primaryTextColor': '#333', 'primaryBorderColor': '#666', 'lineColor': '#555', 'secondaryColor': '#e6e6e6', 'tertiaryColor': '#d9d9d9', 'linkColor': '#ffffff', 'edgeLabelBackground': '#333333'}}}%%
      flowchart TD
        %% Nodes
        Doc[Document]
        Chunk1[Chunk 1]
        Chunk2[Chunk 2]
        Chunk3[Chunk 3]
        Embed1[Vector 1]
        Embed2[Vector 2]
        Embed3[Vector 3]
        VS[(Vector Store)]
        
        %% Styling with grayscale
        classDef document fill:#4b5563,color:#ffffff,stroke-width:2px
        classDef chunk fill:#666666,color:#ffffff,stroke-width:2px
        classDef vector fill:#888888,color:#ffffff,stroke-width:2px
        classDef store fill:#333333,color:#ffffff,stroke-width:2px
        
        %% Apply styles
        class Doc document
        class Chunk1,Chunk2,Chunk3 chunk
        class Embed1,Embed2,Embed3 vector
        class VS store
        
        %% Flow
        Doc -->|Split| Chunk1 & Chunk2 & Chunk3
        
        %% Show overlap
        Chunk1 -.->|Overlap| Chunk2
        Chunk2 -.->|Overlap| Chunk3
        
        Chunk1 -->|Embed| Embed1
        Chunk2 -->|Embed| Embed2
        Chunk3 -->|Embed| Embed3
        
        Embed1 & Embed2 & Embed3 -->|Store| VS
      ```
    </div>
  </Frame>
</div>

<AccordionGroup>
  <Accordion title="max_chunk_size_tokens">
    Maximum size of each chunk in tokens. Larger chunks provide more context but may reduce retrieval precision.
  </Accordion>

  <Accordion title="chunk_overlap_tokens">
    Overlap between consecutive chunks to maintain context and prevent information loss across chunk boundaries.
  </Accordion>
</AccordionGroup>

### Example Implementation

For a complete code example demonstrating RAG integration, check out this [Python example on GitHub](https://github.com/masaic-ai-platform/openai-agents-python/blob/main/examples/open_responses/rag.py). This example shows how to:

* Upload documents
* Create vector stores
* Process files for embedding
* Perform searches with the agentic\_search tool
* Execute direct API calls
* Use the FileSearchTool for simpler queries

### Filtering Results

You can filter search results using file attributes with a structured filter format:

```json theme={null}
"filters": {
  "type": "and",
  "filters": [
    {
      "type": "eq",
      "key": "language",
      "value": "en"
    },
    {
      "type": "eq",
      "key": "category",
      "value": "documentation"
    },
    {
      "type": "gte",
      "key": "version",
      "value": 2.0
    }
  ]
}
```

<Note>
  The filter system supports comparison operators (eq, ne, gt, gte, lt, lte) and logical operators (and, or) for powerful and flexible search filtering. For detailed information, see the [Search API documentation](/rag/search-api).
</Note>

## Best Practices

<Steps>
  <Step title="Document Preparation">
    Use clear, well-structured documents for better search results. Split large documents into logical sections before uploading.
  </Step>

  <Step title="Vector Store Organization">
    Create separate vector stores for different domains or use cases. Use file attributes to organize documents within a vector store.
  </Step>

  <Step title="Query Optimization">
    Craft clear, specific queries for better results. Use filters to narrow down the search scope. Adjust chunking strategy based on your content and query patterns.
  </Step>

  <Step title="Performance Considerations">
    Balance chunk size for optimal search precision and context. Limit the number of search results to what you actually need. Consider caching frequent search results.
  </Step>
</Steps>

## API Reference

For detailed information on individual APIs, refer to the dedicated documentation:

<CardGroup cols={3}>
  <Card title="Files API" icon="file" href="/rag/files-api">
    Upload and manage files
  </Card>

  <Card title="Vector Store API" icon="database" href="/rag/vectorstore-api">
    Create and manage vector stores
  </Card>

  <Card title="Search API" icon="magnifying-glass" href="/rag/search-api">
    Search vector stores for relevant content
  </Card>
</CardGroup>