diff --git a/.gitignore b/.gitignore index 4ef4bd851..ef6886a66 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ **/.definition **/.preview/** .env +.DS_Store \ No newline at end of file diff --git a/fern/docs.yml b/fern/docs.yml index 4099a31fb..ff1e24637 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -175,6 +175,8 @@ navigation: - section: Knowledge Base path: knowledge-base/knowledge-base.mdx contents: + - page: Using the Query Tool + path: knowledge-base/using-query-tool.mdx - page: Integrating with Trieve path: knowledge-base/integrating-with-trieve.mdx - section: Squads diff --git a/fern/knowledge-base/knowledge-base.mdx b/fern/knowledge-base/knowledge-base.mdx index 0740ed4a1..fe8c4d76b 100644 --- a/fern/knowledge-base/knowledge-base.mdx +++ b/fern/knowledge-base/knowledge-base.mdx @@ -8,27 +8,38 @@ slug: knowledge-base ## **What is Vapi's Knowledge Base?** -A [**Knowledge Base**](/api-reference/knowledge-bases/create) 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. +A [**Knowledge Base**](/api-reference/knowledge-bases/create) 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 based on your own data. Knowledge Bases are available through both the Vapi API and dashboard. ### **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. +- **Improved accuracy**: Your assistant can provide responses based on your verified information rather than general knowledge. +- **Enhanced capabilities**: A Knowledge Base enables your assistant to answer complex domain-specific queries with detailed, contextually relevant responses. +- **Customization**: With a Knowledge Base, you can tailor your assistant's responses to specific domains or topics, making it more effective for your particular use case. +- **Up-to-date information**: You control the content, ensuring your assistant always has access to the latest information. - Knowledge Bases are configured through the API, view all configurable properties in the [API Reference](/api-reference/knowledge-bases/create-knowledge-base). + Knowledge Bases are configured through the API or dashboard. For advanced + configuration options, view all configurable properties in the [API + Reference](/api-reference/knowledge-bases/using-query-tool). ## **How to Create a Knowledge Base** -To create a Knowledge Base, follow these steps: +There are two main approaches to creating a Knowledge Base in Vapi: -### **Step 1: Upload Your Files** +1. **Dashboard method**: A simplified approach using the Vapi UI +2. **API method**: A more customizable approach using direct API calls -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. +### **Method 1: Using the Dashboard** + +#### **Step 1: Upload Your Files** + +1. Navigate to `Build > Files` in your Vapi dashboard +2. Click the "Upload" button to add your files +3. Select files in supported formats (`.txt`, `.pdf`, `.docx`, etc.) +4. Wait for the upload to complete - you'll see your files listed in the Files section Files and upload your custom files in Markdown, PDF, plai /> -Alternatively you can upload your files via the API. - -```bash -curl --location 'https://api.vapi.ai/file' \ ---header 'Authorization: Bearer ' \ ---form '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](https://trieve.ai) - -```bash -curl --location 'http://localhost:3001/knowledge-base' \ ---header 'Content-Type: text/plain' \ ---header 'Authorization: Bearer ' \ ---data '{ - "name": "v2", - "provider": "trieve", - "searchPlan": { - "searchType": "semantic", - "topK": 3, - "removeStopWords": true, - "scoreThreshold": 0.7 - }, - "createPlan": { - "type": "create", - "chunkPlans": [ - { - "fileIds": ["", ""], - "websites": ["", ""], - "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. - -```bash -curl --location --request PATCH 'https://api.vapi.ai/assistant/' \ ---header 'Content-Type: text/plain' \ ---header 'Authorization: Bearer ' \ ---data '{ - "model": { - "knowledgeBaseId": "", - "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" - } - ] - } -}' -``` +#### **Step 2: Configure Your Assistant with the Knowledge Base** + +1. Navigate to `Build > Assistant` +2. Select the assistant you want to enhance with the Knowledge Base +3. In the assistant configuration, locate the "Files" or "Knowledge Base" section +4. Select the files you uploaded in Step 1 to associate them with this assistant + + + Select files from your Assistant + + +#### **Step 3: Publish the Assistant** + +1. Review your assistant configuration to ensure all settings are correct +2. Click the "Publish" button to make your changes live +3. This automatically creates a default knowledge base (using the query tool) with the selected files for the assistant + + + When you publish an assistant with selected files, Vapi automatically creates + a query tool with those files configured as a knowledge base. For more + advanced configurations, use the API method described below or see our [Query + Tool documentation](/knowledge-base/using-query-tool). + + +### **Method 2: Using the API** + +For more advanced configurations, you can create and configure Knowledge Bases using the API through the Query Tool. This method offers greater flexibility and control over your knowledge base setup. + + + For detailed instructions on creating and configuring knowledge bases via the + API, please refer to our dedicated guide: [Using the Query Tool for Knowledge + Bases](/knowledge-base/using-query-tool). + + +The API method allows you to: + +- Upload files and obtain file IDs +- Create custom query tools with specific knowledge base configurations +- Configure multiple knowledge bases within a single query tool +- Attach query tools to your assistants +- Set advanced parameters for knowledge retrieval + +This approach is recommended for developers and users who need precise control over their knowledge base implementation or are integrating Vapi into existing systems programmatically. ## **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. +- **Optimize file size**: Keep individual files smaller than 300KB to ensure quick processing and response times. +- **Structure content logically**: Organize your files by topic or category with clear headings and sections. +- **Use clear and concise language**: Write in plain language with well-defined terminology to improve retrieval accuracy. +- **Update regularly**: Refresh your knowledge base files whenever information changes to maintain accuracy. +- **Test thoroughly**: After configuration, test your assistant with various queries to ensure it retrieves information correctly. +- **Provide context**: Include sufficient background information in your files to enable comprehensive responses. +- **Consider file formats**: While plain text works well, structured formats can improve information retrieval for complex topics. For more information on creating effective Knowledge Bases, check out our @@ -140,3 +112,8 @@ curl --location --request PATCH 'https://api.vapi.ai/assistant/' \ 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. + + + Currently, Vapi's Knowledge Base functionality supports Google as a provider + with the gemini-1.5-flash model for knowledge retrieval. + diff --git a/fern/knowledge-base/using-query-tool.mdx b/fern/knowledge-base/using-query-tool.mdx new file mode 100644 index 000000000..5cf65c361 --- /dev/null +++ b/fern/knowledge-base/using-query-tool.mdx @@ -0,0 +1,155 @@ +--- +title: Using the Query Tool for Knowledge Bases +subtitle: >- + Learn how to configure and use the query tool to enhance your voice AI assistants with custom knowledge bases. +slug: knowledge-base/using-query-tool +--- + +## **What is the Query Tool?** + +The Query Tool is a powerful feature that allows your voice AI assistant to access and retrieve information from custom knowledge bases. By configuring a query tool with specific file IDs, you can enable your assistant to provide accurate and contextually relevant responses based on your custom data. + +### **Benefits of Using the Query Tool** + +- **Enhanced contextual understanding**: Your assistant can access specific knowledge to answer domain-specific questions. +- **Improved response accuracy**: Responses are based on your verified information rather than general knowledge. +- **Customizable knowledge retrieval**: Configure multiple knowledge bases for different topics or domains. + + + Currently, the Query Tool only supports Google as a provider with the + gemini-1.5-flash model for knowledge base retrieval. + + +## **How to Configure a Query Tool for Knowledge Bases** + +### **Step 1: Upload Your Files** + +Before creating a query tool, you need to upload the files that will form your knowledge base. You can upload files via the API: + +```bash +curl --location 'https://api.vapi.ai/file' \ +--header 'Authorization: Bearer ' \ +--form 'file=@""' +``` + +After uploading, you'll receive file IDs that you'll need for the next step. + +### **Step 2: Create a Query Tool** + +Use the following API call to create a query tool that references your knowledge base files: + +```bash +curl --location 'https://api.vapi.ai/tool/' \ +--header 'Content-Type: application/json' \ +--header 'Authorization: Bearer ' \ +--data '{ + "type": "query", + "function": { + "name": "product-query" + }, + "knowledgeBases": [ + { + "provider": "google", + "name": "product-kb", + "description": "Use this knowledge base when the user asks or queries about the product or services", + "fileIds": [ + "41a2bd44-d13c-4914-bbf7-b19807dd2cf4", + "ef82ae15-21b2-47bd-bde4-dea3922c1e49" + ] + } + ] +}' +``` + + + The `description` field in the knowledge base configuration helps your + assistant understand when to use this particular knowledge base. Make it + descriptive of the content. + + +### **Step 3: Attach the Query Tool to Your Assistant** + +After creating the query tool, you'll receive a tool ID. Use this ID to attach the tool to your assistant: + +#### Option 1: Using the API + +```bash +curl --location --request PATCH 'https://api.vapi.ai/assistant/ASSISTANT_ID' \ +--header 'Authorization: Bearer ' \ +--data '{ + "model": { + "temperature": 0.2, + "provider": "openai", + "model": "gpt-4o", + "toolIds": [ + "9441840b-6f2f-4b0f-a0fc-de8512549a0c" + ] + } +}' +``` + + + When using the PATCH request, you must include the entire model object, not + just the toolIds field. This will overwrite any existing model configuration. + + +#### Option 2: Using the Dashboard + +1. Navigate to the Assistant section in your Vapi dashboard +2. Select the assistant you want to configure +3. Go to the Tools section +4. Add the query tool by selecting it from the available tools +5. Save and publish your assistant + + + Adding a query tool to your assistant + + +## **Advanced Configuration Options** + +### **Multiple Knowledge Bases** + +You can configure multiple knowledge bases within a single query tool: + +```json +"knowledgeBases": [ + { + "provider": "google", + "name": "product-documentation", + "description": "Use this knowledge base for product specifications and features", + "fileIds": ["file-id-1", "file-id-2"] + }, + { + "provider": "google", + "name": "troubleshooting-guide", + "description": "Use this knowledge base for troubleshooting and support questions", + "fileIds": ["file-id-3", "file-id-4"] + } +] +``` + +### **Knowledge Base Description** + +The description field helps your assistant understand when to use a particular knowledge base. Make it specific and clear: + +```json +"description": "Use this knowledge base when the user asks about pricing, subscription plans, or billing information" +``` + +## **Best Practices for Query Tool Configuration** + +- **Organize by topic**: Create separate knowledge bases for distinct topics to improve retrieval accuracy. +- **Use descriptive names**: Name your knowledge bases clearly to help your assistant understand their purpose. +- **Keep descriptions specific**: Write clear descriptions that tell the assistant exactly when to use each knowledge base. +- **Update regularly**: Refresh your knowledge bases as information changes to ensure accuracy. +- **Test thoroughly**: After configuration, test your assistant with various queries to ensure it retrieves information correctly. + + + For optimal performance, keep individual files under 300KB and ensure they + contain clear, well-structured information. + + +By following these steps and best practices, you can effectively configure the query tool to enhance your voice AI assistant with custom knowledge bases, making it more informative and responsive to user queries. diff --git a/fern/static/images/knowledge-base/assistant.png b/fern/static/images/knowledge-base/assistant.png new file mode 100644 index 000000000..2bfd142a5 Binary files /dev/null and b/fern/static/images/knowledge-base/assistant.png differ diff --git a/fern/static/images/knowledge-base/files.png b/fern/static/images/knowledge-base/files.png index 669376b09..634a1d2f5 100644 Binary files a/fern/static/images/knowledge-base/files.png and b/fern/static/images/knowledge-base/files.png differ diff --git a/fern/static/images/knowledge-base/query-tool.png b/fern/static/images/knowledge-base/query-tool.png new file mode 100644 index 000000000..f00c5587a Binary files /dev/null and b/fern/static/images/knowledge-base/query-tool.png differ