28 KiB
AI Assistant Setup Guide with Vector Search
🤖 Complete Guide to Launching an Intelligent Assistant
This document describes the step-by-step process of setting up an AI assistant for solving business tasks through spreadsheets and vector search.
📚 What You'll Set Up
After completing the instructions, you will have:
✅ Working AI assistant with local model (Ollama)
✅ Knowledge base for customer responses (FAQ)
✅ Supplier work automation
✅ Employee training system
✅ Vector search on your data
✅ Significant time and resource savings
💡 Economic Impact: See AI Assistant - detailed description of all capabilities and savings calculations.
⏱️ Setup Time
- Quick Setup: 20-30 minutes (basic FAQ)
- Full Setup: 1-2 hours (all capabilities)
Step 1: Installing and Running Ollama
1.1 Checking Ollama Status
- Go to Settings → Integrations tab
- Find the "Ollama" block and click "Details"
- Check connection status:
- ✅ "Ollama is running" — ready, proceed to step 1.3
- ❌ "Ollama API not responding" — proceed to step 1.2
1.2 Starting Ollama (if not running)
If Ollama is not running, execute in terminal:
# For Docker (recommended)
docker-compose up -d ollama
# Or locally
ollama serve
Refresh the page and check status again.
1.3 Installing AI Model
- In the Ollama section, click "Install Model"
- Select model:
- qwen2.5:7b (recommended) — for Russian, 4.7 GB
- llama2:7b — for English, 3.8 GB
- mistral:7b — universal, 4.1 GB
- Click "Install"
- Wait for download to complete (5-10 minutes depending on internet speed)
💡 Tip: Model downloads once and is stored locally
1.4 Installing Embedding Model
- In the same section, find "Install Embedding Model"
- Select model:
- mxbai-embed-large:latest (recommended) — 670 MB
- nomic-embed-text:latest — alternative, 274 MB
- Click "Install"
⚠️ Important: Embedding model is needed for vector search (RAG)
Step 2: Creating Knowledge Base (Spreadsheets)
2.1 Creating FAQ Table
- Go to Tables (in main menu)
- Click "+ Create Table"
- Fill in:
- Name:
FAQ - Frequently Asked Questions - Description:
Knowledge base for AI assistant customer service
- Name:
- Click "Create"
2.2 Configuring Table Columns
Add the following columns:
Column 1: Question (required for RAG)
- Click "+ Add Column"
- Fill in:
- Name:
Question - Type:
Text - Purpose: Select
Question for AI⭐
- Name:
- Click "Save"
⚠️ Critical: Must select purpose "Question for AI" — this field will be indexed for vector search
Column 2: Answer (required for RAG)
- Click "+ Add Column"
- Fill in:
- Name:
Answer - Type:
Text - Purpose: Select
AI Answer⭐
- Name:
- Click "Save"
Column 3: Product (optional, for filtering)
- Click "+ Add Column"
- Fill in:
- Name:
Product - Type:
Multiple Choice - Options:
Basic,Premium,Corporate - Purpose: Select
Product Filter
- Name:
- Click "Save"
Column 4: Tags (optional, for categorization)
- Click "+ Add Column"
- Fill in:
- Name:
Tags - Type:
Multiple Choice - Options:
Payment,Delivery,Return,Warranty,Support - Purpose: Select
User Tags
- Name:
- Click "Save"
Column 5: Priority (optional)
- Click "+ Add Column"
- Fill in:
- Name:
Priority - Type:
Number - Purpose: Select
Priority
- Name:
- Click "Save"
💡 Tip: Questions with higher priority will be shown to AI first
2.3 Filling Knowledge Base
Add typical questions and answers:
Example 1: Payment
| Question | Answer | Product | Tags | Priority |
|---|---|---|---|---|
| How to pay for order? | We accept payment by bank card, PayPal, or bank transfer. Choose convenient method when placing order. | All | Payment | 10 |
| Can I pay in installments? | Yes, for orders from 50,000₽ installment plan available for 3, 6 or 12 months without overpayment. | Premium, Corporate | Payment | 8 |
Example 2: Delivery
| Question | Answer | Product | Tags | Priority |
|---|---|---|---|---|
| How long does delivery take? | Standard delivery: 3-5 business days in Russia. Express delivery: 1-2 days in major cities. | All | Delivery | 10 |
| How much does delivery cost? | Free delivery for orders from 5,000₽. For orders less than 5,000₽ delivery cost is 300₽. | All | Delivery | 9 |
Example 3: Return
| Question | Answer | Product | Tags | Priority |
|---|---|---|---|---|
| How to return product? | Return possible within 14 days from receipt. Product must be in original packaging, with preserved appearance. Contact support to process return. | All | Return | 10 |
| When will money be returned? | Refund processed within 5-10 business days after product received at our warehouse. | All | Return | 8 |
💡 Recommendation: Add minimum 20-30 questions for quality AI work. More questions = more accurate answers!
2.4 Activating Table as AI Source
- In top right corner of table, find ⚙️ Table Settings
- Enable toggle "Use as AI Source" ✅
- Click "Save"
✅ Done! Table is now indexed for vector search
Step 3: Configuring AI Provider (Ollama)
3.1 Opening Ollama Settings
- Go to Settings → Integrations
- Find "Ollama" block and click "Details"
3.2 Checking Base URL
- Check Base URL field:
- For Docker:
http://ollama:11434✅ - For local:
http://localhost:11434
- For Docker:
- If URL is incorrect, fix and click "Save"
3.3 Selecting Model
- In "Model (LLM)" field, select installed model:
qwen2.5:7b(recommended for Russian)
- In "Embeddings Model" field, select:
mxbai-embed-large:latest
- Click "Save"
Step 4: Configuring AI Assistant
4.1 Opening Assistant Settings
- Go to Settings → Integrations
- Find "AI Assistant" block and click "Details"
4.2 Configuring System Prompt
In "System Prompt" field, enter instructions for AI:
Basic Prompt (to start):
You are a professional customer support assistant.
Rules:
1. Answer politely and professionally
2. Use information from knowledge base
3. If information not available — suggest contacting operator
4. Answer briefly and to the point
5. Always end with question "How else can I help?"
Advanced Prompt (with personalization):
You are a professional customer support assistant for "Your Company Name".
About company:
- We are engaged in [brief business description]
- Our values: quality, reliability, customer focus
Communication style:
- Friendly but professional
- Address customer as "You"
- Use emojis moderately (1-2 per message)
Response rules:
1. MANDATORY: Answer ONLY in Russian. All questions and answers must be in Russian
2. First search answer in knowledge base (RAG)
3. If found — answer based on found information
4. If not found — honestly say and suggest operator help
5. Don't make up information about prices, terms, conditions
6. For complex questions suggest contacting manager
Always end with: "How else can I help? 😊"
4.3 Selecting Models
- LLM Model: Select
qwen2.5:7b (ollama) - Embedding Model: Select
mxbai-embed-large:latest (ollama)
💡 Tip: Models automatically pulled from Ollama settings
📊 Context Window Size:
- Qwen2.5:7b: Base context = 32,768 tokens (~24,000 Russian words)
- Total data sent to model:
- System prompt: ~500-2000 characters (~300-1200 tokens)
- Conversation history: up to 20 messages (~100-500 tokens per message = ~2000-10000 tokens)
- RAG context: ~500-2000 tokens (from found data)
- Current question: ~50-200 tokens
- Total: approximately 3,000-15,000 tokens (sufficient reserve)
- If larger context needed → use Qwen3 with YaRN (up to 131K tokens)
4.4 Selecting RAG Table
- In "Selected RAG Tables" field, select created table:
FAQ - Frequently Asked Questions
- Click "Save"
4.5 Configuring AI Rules
Create rule set for managing AI behavior:
- Click "Create" button next to "Rule Set" field
- In modal window, fill in:
Name: Hybrid Mode (RAG + Generation)
Description: AI first searches knowledge base, if not found — generates answer
Rules (JSON):
{
"checkUserTags": true,
"searchRagFirst": true,
"generateIfNoRag": true,
"temperature": 0.7,
"maxTokens": 500
}
- Click "Save"
- Select created rule in dropdown
💡 What parameters mean:
checkUserTags: true— consider user tags when searchingsearchRagFirst: true— first search knowledge basegenerateIfNoRag: true— generate answer if nothing foundtemperature: 0.7— balance between accuracy and creativity (0.0-1.0)maxTokens: 500— maximum answer length
4.6 RAG Search Settings
Expand "🔍 RAG Search Settings" section:
Basic Settings:
- Search Method: Select
Hybrid Search(recommended) - Maximum Results:
5 - Relevance Threshold:
0.1(from 0.01 to 1.0)
Keyword Extraction:
- ✅ Enable Keyword Extraction
- Minimum Word Length:
3 - Maximum Keywords:
10 - ✅ Remove Stop Words
Search Weights (for hybrid):
- Semantic Search:
70%(accuracy) - Keyword Search:
30%(speed)
Additional Settings:
- ✅ Fuzzy Search (for typos)
- ✅ Word Stemming (finds different word forms)
- ☐ Synonym Search (currently disabled)
4.7 Saving Settings
Click "Save" button at bottom of form.
Step 5: Testing AI Assistant
5.1 Using Built-in Tester
- On AI assistant settings page, scroll down to "🔍 System Monitoring" block
- In "🧠 RAG Functionality Test" section:
- Ensure table
FAQ - Frequently Asked Questionsis selected - Enter test question:
How to pay for order? - Click "Test RAG"
- Ensure table
- Observe process:
- 🔍 Searching answer in knowledge base... (vector search)
- 🤖 Generating answer with AI... (LLM generation)
- ✅ Done!
- Check result:
- Answer from your table should be displayed
- Score (similarity score): closer to 0 is better
💡 Good Score: from -300 to 0 (answer found)
⚠️ Bad Score: greater than 300 (answer not found, AI will make up its own)
5.2 Testing via Web Chat
- Go to application main page
- Find "💬 Chat with AI" widget (usually bottom right)
- Click widget to open chat
- Enter question:
How much does delivery cost? - Check AI response
Expected Result:
🤖 AI Assistant:
Free delivery for orders from 5,000₽.
For orders less than 5,000₽ delivery cost is 300₽.
How else can I help? 😊
5.3 Testing Different Scenarios
Try asking various questions:
✅ Question from knowledge base:
User: "How to return product?"
AI: [Answer from FAQ table]
⚠️ Question NOT from knowledge base:
User: "What's the weather today?"
AI: "Sorry, I specialize in questions about our company and products.
For weather questions, please contact specialized services.
How else can I help?"
🎯 Question with typo:
User: "How to pay for order?" (typo)
AI: [Will find correct answer thanks to fuzzy search]
Step 6: Advanced Capabilities (Optional)
6.1 Creating Supplier Table
"Supplier Database" Table Structure
- Create new table:
Supplier Database - Add columns:
| Column | Type | Description |
|---|---|---|
| Company Name | Text | Supplier name |
| Product Category | Multiple Choice | Electronics, Furniture, Clothing, etc. |
| Contact Person | Text | Manager name |
| Text | Email address | |
| Phone | Text | Contact phone |
| Prices | Text | Price list (brief description) |
| Payment Terms | Text | Deferred payment, prepayment, etc. |
| Minimum Order | Number | Minimum order amount |
| Delivery Time | Text | Delivery terms |
| Rating | Number | Rating from 1 to 10 |
| Notes | Text | Additional information |
- Activate as AI source
- Fill with your supplier data
Prompt for AI Purchaser
Add to system prompt:
ADDITIONALLY - Working with Suppliers:
When user asks about suppliers:
1. Search in "Supplier Database" base
2. Filter by product category
3. Sort by rating and terms
4. Provide TOP-3 recommendations
Response format:
🏆 TOP-3 suppliers for "[category]":
1. [Name] ⭐ [Rating]/10
📧 [Email] | 📞 [Phone]
💰 Terms: [Payment Terms]
🚚 Delivery: [Delivery Time]
📦 Minimum: [Minimum Order]₽
2. ...
3. ...
I recommend contacting [First Supplier Name] — best terms.
6.2 Creating Employee Training Table
"Employee Knowledge Base" Table Structure
- Create new table:
Employee Knowledge Base - Add columns:
| Column | Type | Description |
|---|---|---|
| Question | Text | Employee question (purpose: Question for AI) |
| Answer | Text | Detailed answer (purpose: AI Answer) |
| Category | Multiple Choice | Sales, HR, Finance, IT, Marketing |
| Department | Multiple Choice | Which department it's relevant for |
| Difficulty | Number | From 1 (simple) to 5 (complex) |
| Instructions | Text | Step-by-step instructions (if any) |
| Links | Text | Links to documents/videos |
| Update Date | Date | When information was updated |
- Example questions:
"Sales" Category:
- "How to process customer return?"
- "What discounts can be given to regular customers?"
- "How to work with corporate customers?"
"HR" Category:
- "How to apply for vacation?"
- "Where to contact for sick leave?"
- "How does new employee onboarding work?"
"IT" Category:
- "How to get access to corporate email?"
- "What to do with VPN problems?"
- "How to create support ticket?"
6.3 Creating Table Relationships
Example: "Customers" → "Orders" Relationship
-
Create "Customers" table:
- Name, Email, Phone, Status (VIP/Regular)
-
Create "Orders" table:
- Order Number, Date, Amount
-
In "Orders" table, add column:
- Name:
Customer - Type:
Relation - Related Table: select
Customers - Display Field: select
Name
- Name:
-
Add another column in "Orders":
- Name:
Customer Email - Type:
Lookup - Relation Through: select
Customercolumn - Lookup Field: select
Email
- Name:
Result: When selecting customer, their Email is automatically filled!
Using AI with Related Tables
AI automatically understands relationships and can answer questions:
User: "Show all orders for customer Ivanov"
AI: [Searches Orders table, filters by customer Ivanov]
Step 7: Telegram and Email Integration (Optional)
7.1 Setting Up Telegram Bot
- Go to Settings → Integrations → Telegram
- Create bot via @BotFather in Telegram:
- Send
/newbot - Choose bot name and username
- Copy Bot Token
- Send
- In DLE settings, enter:
- Bot Token: paste token from BotFather
- Bot Username: your bot username (e.g.,
@mycompany_bot)
- Click "Save"
- In AI assistant settings, select this Telegram bot in "Telegram Bot" field
Result: AI will respond to Telegram messages!
7.2 Setting Up Email Integration
- Go to Settings → Integrations → Email
- Fill IMAP settings (for receiving emails):
- IMAP Host:
imap.gmail.com(for Gmail) - IMAP Port:
993 - IMAP User: your email
- IMAP Password: app password (not main password!)
- IMAP Host:
- Fill SMTP settings (for sending emails):
- SMTP Host:
smtp.gmail.com - SMTP Port:
587 - SMTP User: your email
- SMTP Password: app password
- From Email: email for sending
- SMTP Host:
- Click "Test IMAP" and "Test SMTP" to verify
- Click "Save"
- In AI assistant settings, select this Email in "Email Contact" field
⚠️ Important for Gmail: Create "App Password" in Google security settings
Result: AI will automatically respond to incoming emails!
Step 8: Monitoring and Optimization
8.1 Checking Service Status
- Go to Settings → Integrations → AI Assistant
- Scroll down to "🔍 System Monitoring"
- Click "🔄 Refresh Status"
- Check statuses:
- 🟢 Backend: should be "Running"
- 🟢 Postgres: should be "Running"
- 🟢 Ollama: should show number of models
- 🟢 Vector Search: should be "Running"
⚠️ If something is red (🔴) — see "Troubleshooting" section below
8.2 Analyzing Answer Quality
Regularly check AI answer quality:
-
Score in RAG Tester:
- -300 to 0 ✅ — excellent match
- 0 to 300 ⚠️ — average match
- >300 ❌ — match not found
-
If Score is Bad:
- Add more similar questions to table
- Use different phrasings of same question
- Increase relevance threshold (e.g., to 0.2)
8.3 Optimizing RAG Settings
Experiment with settings to improve results:
For More Accurate Answers:
Search Method: Semantic
Relevance Threshold: 0.05 (lower = stricter)
Weights: Semantic 100% / Keywords 0%
For Faster Answers:
Search Method: Keyword Search
Maximum Results: 3
For Balance (Recommended):
Search Method: Hybrid
Weights: Semantic 70% / Keywords 30%
Relevance Threshold: 0.1
✅ AI Assistant Ready to Work!
What You Now Have
✅ Local AI Assistant without cloud dependency
✅ FAQ Knowledge Base for customer responses
✅ Vector Search for accurate answers
✅ Configured Rules for AI behavior
✅ Monitoring System for quality control
Economic Impact
With proper AI assistant setup, you will get:
✅ Task Automation - freeing time for strategy
✅ Improved Service Quality - AI works 24/7 without fatigue
✅ Reduced Operating Costs - less staff on routine tasks
✅ Faster Decision Making - instant access to information
💡 Detailed Information: See AI Assistant - Complete Description - detailed description of all capabilities, use cases, and savings calculations.
📚 Next Steps
Expand AI Capabilities
-
Add More Tables:
- Partner knowledge base
- Employee instructions
- Product catalog
- Contact database
-
Create Rules for Different Scenarios:
- Strict mode (RAG only) — for finance
- Creative mode (more generation) — for marketing
- Hybrid mode (balance) — for support
-
Integrate with Other Systems:
- CRM (customer synchronization)
- Warehouse system (inventory)
- Accounting (invoices and payments)
Train Your Team
- Show employees how AI works
- Explain how to add new questions to base
- Establish regular knowledge base update process
- Assign responsible person for AI answer quality
🆘 Troubleshooting
Problem: Ollama Not Starting
Symptoms: Status "Ollama API not responding"
Solution:
# Check container
docker ps | grep ollama
# Restart
docker-compose restart ollama
# Check logs
docker-compose logs ollama
Problem: AI Answers Inaccurately
Symptoms: Answers don't match knowledge base
Solution:
- Check Score in tester (should be < 300)
- Add more question variations to table
- Decrease relevance threshold (e.g., to 0.05)
- Check that columns have correct purposes ("Question for AI", "AI Answer")
Problem: Vector Search Not Working
Symptoms: Vector Search status shows error
Solution:
- Check if Embedding model is installed
- Rebuild index: on table page click "🔄 Rebuild Index"
- Check that table is activated as AI source
Problem: AI Answers in Wrong Language
Symptoms: Answers in English instead of Russian
Solution:
- Change system prompt, adding at start:
ALWAYS answer in Russian. - Use
qwen2.5:7bmodel instead ofllama2:7b - In AI rules, set
"language": "ru"
Problem: Slow Responses
Symptoms: AI responds longer than 5-10 seconds
Solution:
- Use smaller model (
mistral:7binstead ofqwen2.5:14b) - Decrease
maxResultsin RAG settings (e.g., to 3) - Disable "Synonym Search" in additional settings
- Use SSD for storing models
📖 Additional Documentation
Learn AI Capabilities
- 🤖 AI Assistant - Complete Description - all capabilities and use cases
- 📊 Spreadsheet System - technical description of tables (temporary)
- ⚙️ AI Configuration - technical setup details
General Documentation
- 🛡️ Security - how AI protects your data
- 💼 Blockchain for Business - AI integration with blockchain
- 📋 FAQ - frequently asked questions
Support
- 💬 Support Chat: https://hb3-accelerator.com/
- 📧 Email: info@hb3-accelerator.com
- 📚 Knowledge Base: https://hb3-accelerator.com
🔧 Technical Documentation (for Developers)
AI System Architecture
┌───────────────────────────────────────────────────────────┐
│ AI Assistant Configuration in DLE │
├───────────────────────────────────────────────────────────┤
│ │
│ 🤖 AI Providers: │
│ ├── OpenAI (GPT-4, GPT-3.5) │
│ ├── Anthropic (Claude) │
│ ├── Google (Gemini) │
│ └── Ollama (local models) │
│ │
│ ⚙️ AI Settings: │
│ ├── System Prompt │
│ ├── LLM Model Selection │
│ ├── Embedding Model Selection │
│ ├── RAG Table Selection │
│ ├── Rules │
│ └── RAG Search Settings │
│ │
│ 📋 Rules: │
│ ├── JSON behavior configuration │
│ ├── Create/edit/delete │
│ └── Link to AI assistant │
│ │
│ 🔗 Integrations: │
│ ├── Email (IMAP + SMTP) │
│ └── Telegram Bot │
│ │
│ 🔍 RAG: │
│ ├── Table selection for search │
│ ├── Search settings (hybrid/semantic) │
│ ├── Relevance threshold │
│ └── Keyword extraction │
│ │
│ 📊 Monitoring: │
│ ├── Service status (Backend, Ollama, Postgres) │
│ ├── RAG functionality test │
│ └── Progress tracking │
│ │
└───────────────────────────────────────────────────────────┘
Database
Table: ai_providers_settings
CREATE TABLE IF NOT EXISTS ai_providers_settings (
id SERIAL PRIMARY KEY,
provider_encrypted TEXT, -- Provider: openai, anthropic, google, ollama
api_key_encrypted TEXT, -- API key (encrypted)
base_url_encrypted TEXT, -- Base URL for API
selected_model_encrypted TEXT, -- Selected LLM model
embedding_model_encrypted TEXT, -- Selected Embedding model
created_at TIMESTAMP NOT NULL DEFAULT NOW(),
updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
Table: ai_assistant_settings
CREATE TABLE IF NOT EXISTS ai_assistant_settings (
id SERIAL PRIMARY KEY,
system_prompt_encrypted TEXT, -- System prompt
selected_rag_tables INTEGER[], -- Array of RAG table IDs
languages TEXT[], -- Array of supported languages
model_encrypted TEXT, -- Selected LLM model
embedding_model_encrypted TEXT, -- Selected Embedding model
rules JSONB, -- Rules (DEPRECATED)
rules_id INTEGER REFERENCES ai_assistant_rules(id), -- Rule reference
telegram_settings_id INTEGER, -- Telegram bot reference
email_settings_id INTEGER, -- Email settings reference
rag_settings JSONB, -- RAG search settings
updated_at TIMESTAMP DEFAULT NOW(),
updated_by INTEGER
);
Table: ai_assistant_rules
CREATE TABLE IF NOT EXISTS ai_assistant_rules (
id SERIAL PRIMARY KEY,
name TEXT NOT NULL, -- Rule set name
description TEXT, -- Rule description
rules JSONB NOT NULL, -- JSON configuration
rules_encrypted TEXT, -- Encrypted version of rules
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
Backend API
AI Provider Settings
- GET
/settings/ai-settings/:provider— Get provider settings - PUT
/settings/ai-settings/:provider— Save provider settings - DELETE
/settings/ai-settings/:provider— Delete provider settings - GET
/settings/ai-settings/:provider/models— Get model list - POST
/settings/ai-settings/:provider/verify— Verify API key
AI Assistant Settings
- GET
/settings/ai-assistant— Get assistant settings - PUT
/settings/ai-assistant— Save assistant settings
AI Rules
- GET
/settings/ai-assistant-rules— Get all rules - GET
/settings/ai-assistant-rules/:id— Get rule by ID - POST
/settings/ai-assistant-rules— Create rule - PUT
/settings/ai-assistant-rules/:id— Update rule - DELETE
/settings/ai-assistant-rules/:id— Delete rule
Ollama (Local Models)
- GET
/ollama/status— Check Ollama status - GET
/ollama/models— Get model list - POST
/ollama/install— Install model - DELETE
/ollama/models/:modelName— Delete model
Frontend Pages
/settings/ai— Main integrations page/settings/ai/:provider— AI provider settings/settings/ai/assistant— AI assistant settings
Message Processing Flow
1. User → Message
↓
2. UnifiedMessageProcessor
↓
3. Language Check (Russian only)
↓
4. Deduplication (message hash)
↓
5. Load Settings (aiAssistantSettingsService)
↓
6. Load Rules (aiAssistantRulesService)
↓
7. RAG Search (ragService)
├── Semantic Search (vector search)
├── Keyword Search
└── Hybrid Search
↓
8. Generate Answer (generateLLMResponse)
├── System Prompt
├── Conversation History
├── RAG Context
└── Rules
↓
9. Answer → User
Security
- Encryption: All sensitive fields encrypted with AES-256
- Access Rights: Only administrators can change settings
- Validation: All input data and API keys validated
© 2024-2025 Tarabanov Alexander Viktorovich. All rights reserved.
Document Version: 1.0.0
Creation Date: October 25, 2025