Introduction to Knowledge Bases

Learn how to create and integrate custom knowledge bases into your voice AI assistants.

What is Vapi’s Knowledge Base?

A Knowledge Base is a collection of custom files that contain information on specific topics or domains. By integrating a Knowledge Base into your voice AI assistant, you can enable it to provide more accurate and informative responses to user queries. This is currently available in Vapi via the API, and will be on the dashboard soon.

Why Use a Knowledge Base?

Using a Knowledge Base with your voice AI assistant offers several benefits:

  • Improved accuracy: By integrating custom files into your assistant, you can ensure that it provides accurate and up-to-date information to users.
  • Enhanced capabilities: A Knowledge Base enables your assistant to answer complex queries and provide detailed responses to user inquiries.
  • Customization: With a Knowledge Base, you can tailor your assistant’s responses to specific domains or topics, making it more effective and informative.

Knowledge Bases are configured through the API, view all configurable properties in the API Reference.

How to Create a Knowledge Base

To create a Knowledge Base, follow these steps:

Step 1: Upload Your Files

Navigate to Platform > Files and upload your custom files in Markdown, PDF, plain text, or Microsoft Word (.doc and .docx) format to Vapi’s Knowledge Base.

Adding files to your Knowledge Base
Adding files to your Knowledge Base

Alternatively you can upload your files via the API.

$curl --location 'https://api.vapi.ai/file' \
>--header 'Authorization: Bearer <YOUR_API_KEY>' \
>--form 'file=@"<PATH_TO_YOUR_FILE>"'

Step 2: Create a Knowledge Base

Use the ID of the uploaded file to create a Knowledge Base along with the KB configurations.

  1. Provider: trieve
$curl --location 'http://localhost:3001/knowledge-base' \
>--header 'Content-Type: text/plain' \
>--header 'Authorization: Bearer <YOUR_API_KEY>' \
>--data '{
>    "name": "v2",
>    "provider": "trieve",
>    "searchPlan": {
>        "searchType": "semantic",
>        "topK": 3,
>        "removeStopWords": true,
>        "scoreThreshold": 0.7
>    },
>    "createPlan": {
>        "type": "create",
>        "chunkPlans": [
>            {
>                "fileIds": ["<FILE_ID_1>", "<FILE_ID_2>"],
>                "websites": ["<WEBSITE_1>", "<WEBSITE_2>"],
>                "targetSplitsPerChunk": 50,
>                "splitDelimiters": [".!?\n"],
>                "rebalanceChunks": true
>            }
>        ]
>    }
>}'

Configuration Options

Search Plan Options
  • searchType (required): The search method used for finding relevant chunks. Available options:
    • fulltext: Traditional text search
    • semantic: Semantic similarity search
    • hybrid: Combines fulltext and semantic search
    • bm25: BM25 ranking algorithm
  • topK (optional): Number of top chunks to return. Default varies by implementation
  • removeStopWords (optional): When true, removes common stop words from the search query. Default: false
  • scoreThreshold (optional): Filters out chunks based on their similarity score:
    • For cosine distance: Excludes chunks below the threshold
    • For Manhattan Distance, Euclidean Distance, and Dot Product: Excludes chunks above the threshold
    • Set to 0 or omit for no threshold
Chunk Plan Options
  • fileIds (optional): Array of file IDs to include in the vector store
  • websites (optional): Array of website URLs to crawl and include in the vector store
  • targetSplitsPerChunk (optional): Number of splits per chunk. Default: 20
  • splitDelimiters (optional): Array of delimiters used to split text before chunking. Default: [".!?\n"]
  • rebalanceChunks (optional): When true, evenly distributes remainder splits across chunks. For example, 66 splits with targetSplitsPerChunk: 20 will create 3 chunks with 22 splits each. Default: true

Step 3: Create an Assistant

Create a new assistant in Vapi and, on the right sidebar menu. Add the Knowledge Base to your assistant via the PATCH endpoint. Also make sure you customize your assistant’s system prompt to utilize the Knowledge Base for responding to user queries.

$curl --location --request PATCH 'https://api.vapi.ai/assistant/<ASSISTANT_ID>' \
>--header 'Content-Type: text/plain' \
>--header 'Authorization: Bearer <YOUR_API_KEY>' \
>--data '{
>  "model": {
>    "knowledgeBaseId": "<KNOWLEDGE_BASE_ID>",
>    "temperature": 0.2,
>    "provider": "openai",
>    "model": "gpt-4o",
>    "messages": [
>      {
>        "content": "You are a smart assistant who responds to user queries using the information you know, or information supplied by outside context.",
>        "role": "system"
>      }
>    ]
>  }
>}'

Best Practices for Creating Effective Knowledge Bases

  • Organize Your files: Organize your files by topic or category to ensure that your assistant can quickly retrieve relevant information.
  • Use Clear and concise language: Use clear and concise language in your files to ensure that your assistant can accurately understand and respond to user queries.
  • Keep your files up-to-date: Regularly update your files to ensure that your assistant provides the most accurate and up-to-date information.

For more information on creating effective Knowledge Bases, check out our tutorial on Best Practices for Knowledge Base Creation.

By following these guidelines, you can create a comprehensive Knowledge Base that enhances the capabilities of your voice AI assistant and provides valuable information to users.

Built with