MxChat Migration Tool
Seamlessly migrate your entire knowledge base and actions between embedding models and vector databases. No more deleting everything and starting over – preserve all your content while upgrading to better AI models or switching database providers.
Requirements
- MxChat Basic Plugin (installed and activated)
- MxChat Pro License (active)
- Valid API key for your target embedding model
- WordPress 5.0+ and PHP 7.4+
Quick Setup
- Install the Plugin: Upload and activate MxChat Migration Tool through your WordPress plugins page
- Navigate to Tool: Go to
MxChat → Migration Toolin your WordPress admin - Review Current Setup: See your current database (WordPress or Pinecone) and embedding model
- Backup Database: Always backup your database before starting a migration
- Verify API Keys: Ensure you have valid API keys for your target embedding model
Why Migration is Necessary
Embeddings Aren’t Compatible
Each embedding model creates vectors in different dimensional spaces. OpenAI’s ada-002 creates 1536-dimensional vectors, while their 3-large creates 3072-dimensional vectors. You cannot mix embeddings from different models – they simply won’t match correctly during semantic search.
The Old Way: Delete Everything
Previously, switching models meant deleting your entire knowledge base and all actions, then manually re-uploading everything. This could take hours of work and meant losing all your carefully curated content during the transition.
The New Way: Seamless Migration
Our migration tool automatically regenerates all embeddings with your new model while preserving every piece of content, metadata, and configuration. Switch models in minutes instead of hours, with zero data loss.
Supported Embedding Models
OpenAI
text-embedding-ada-002 – 1536 dimensions. Legacy model, still reliable.
text-embedding-3-small – 1536 dimensions. Best value (5x cheaper than ada-002, better quality).
text-embedding-3-large – 3072 dimensions. Highest quality for demanding applications.
Voyage AI
voyage-2 – 1024 dimensions. Optimized for general use.
voyage-large-2 – 1536 dimensions. Enhanced performance.
voyage-3-large – 2048 dimensions. Latest generation model.
Google Gemini
gemini-embedding-001 – 1536 dimensions. Integrated with Google’s AI ecosystem.
Vector Database Options
WordPress Database
Store embeddings locally in your WordPress database. Best for maximum control, privacy, and simpler setup. No external dependencies or recurring costs.
Pinecone Vector Database
Enterprise-grade vector database optimized for large-scale semantic search. Best for handling massive datasets (50K+ entries) with lightning-fast retrieval.
Supported Migration Paths
- WordPress → Pinecone: Scale to larger datasets with better performance
- Pinecone → WordPress: Reduce costs and simplify infrastructure
- WordPress → WordPress: Change embedding model while staying on WordPress
- Pinecone → Pinecone: Upgrade embedding model while staying on Pinecone
Key Features
Batch Processing
Process migrations in configurable batches (1-50 items) to avoid API rate limits and server timeouts. Reliable migration for databases of any size, from 100 to 10,000+ entries.
Real-Time Progress Tracking
Monitor your migration with live progress bars and detailed logs. See exactly what’s being processed, catch errors instantly, and know when your migration is complete.
Smart Threshold Adjustment
Automatically adjusts action similarity thresholds when switching embedding models. Different models produce vastly different similarity scores, and this feature ensures your actions continue working correctly.
Migration History
Track every migration with detailed logs showing what was migrated, when, and any errors encountered. Perfect for auditing and troubleshooting.
Granular Settings Control
Choose whether to update your MxChat settings after migration or keep them separate. Great for testing new configurations before going live.
How to Migrate
- Review Current Configuration: The page displays your current database, embedding model, and content counts
- Select What to Migrate: Choose Knowledge Base + Actions (recommended), Knowledge Base Only, or Actions Only
- Configure Target Database: Select WordPress or Pinecone. If Pinecone, enter API Key, Host, and optionally Namespace
- Select Target Embedding Model: Choose from OpenAI, Voyage AI, or Google Gemini models
- Enter API Key: Provide the API key for your selected embedding provider
- Set Batch Size: Default is 10 (recommended for most cases). Lower for slower servers, higher for faster ones
- Start Migration: Click “Start Migration” and confirm the action
- Monitor Progress: Watch the real-time progress bar and log output
- Finalize: Once complete, choose whether to update your MxChat settings to use the new configuration
Understanding Smart Threshold Adjustment
Why It’s Needed
Different embedding models produce vastly different similarity scores for the same content:
- ada-002: Typically 85-95% similarity for good matches
- 3-small: Typically 50-70% similarity for the same matches
- 3-large: Typically 45-65% similarity for the same matches
Without adjustment, your actions would stop triggering after migration because the thresholds would be too high for the new model’s scoring range.
How It Works
The plugin automatically adjusts action similarity thresholds based on empirical testing:
- ada-002 → 3-small: 30% reduction (e.g., 0.85 → 0.60)
- ada-002 → 3-large: 32% reduction (e.g., 0.85 → 0.58)
- 3-small → ada-002: 43% increase (e.g., 0.65 → 0.93)
Fine-Tuning After Migration
If actions don’t trigger correctly after migration:
- Actions trigger too easily: Increase threshold by 0.05
- Actions rarely trigger: Decrease threshold by 0.05
- Test each action individually and adjust as needed
Best Practices
Before Migration
- Backup Your Database: Always create a complete backup before major migrations
- Test API Keys: Verify all API keys work correctly with test requests
- Check API Quotas: Ensure sufficient quota for your content volume
- Test on Staging: Run migration on staging environment before production
- Review Content: Clean up unnecessary content to reduce migration time
During Migration
- Keep Browser Tab Open: Don’t close or refresh the page during migration
- Monitor Progress: Watch for error messages in the log
- Be Patient: Large migrations may take time due to API rate limits
- Don’t Edit Content: Avoid modifying knowledge base or actions during migration
After Migration
- Test Chatbot Functionality: Ask common questions to verify responses
- Review Action Thresholds: Test each action individually
- Check Migration History: Verify all items processed successfully
- Keep Backup: Maintain backup for 30+ days in case rollback is needed
Batch Size Configuration
1-5 Items per Batch
Use when: Slow servers, strict API limits, or stability is critical
Speed: Slowest | Reliability: Highest
10 Items per Batch (Default)
Use when: Most standard WordPress installations
Speed: Medium | Reliability: High
25-50 Items per Batch
Use when: Fast servers with high API quotas
Speed: Fastest | Reliability: Lower (more prone to timeouts)
Troubleshooting
Migration Fails to Start
Common Causes:
- Invalid or missing API keys
- Incorrect Pinecone host format
- Missing required fields
Solutions:
- Verify all API keys are correct and have sufficient quota
- Ensure Pinecone host is formatted correctly:
your-index-abc123.svc.pinecone.io(no https://) - Fill in all required fields before starting
Migration Stalls or Times Out
Symptoms: Progress stops, no new log entries
Solutions:
- Reduce batch size to 5 or lower
- Check if you’re hitting API rate limits (wait 60 seconds)
- Increase PHP max_execution_time if possible
- Refresh page and check migration history to see if it completed
Actions Not Triggering After Migration
Symptoms: Actions worked before but don’t trigger after migration
Cause: Thresholds may need manual adjustment
Solution:
- Navigate to MxChat → Actions
- Test each action with sample queries
- Adjust similarity thresholds up or down by 0.05 until working correctly
Settings Don’t Update After Migration
Symptoms: Migration completes but settings show old model/database
Solutions:
- Hard refresh browser (Ctrl+F5 or Cmd+Shift+R)
- Navigate to MxChat → Settings to verify
- Manually update settings if needed
Pinecone Count Shows 0
Symptoms: Migration shows success but Pinecone count = 0
Cause: Display issue or namespace mismatch
Solutions:
- Check Pinecone dashboard directly
- Verify namespace matches in Pinecone addon settings
- Wait 24 hours for count to update (chatbot will work regardless)
Some Items Fail During Migration
Solutions:
- Review error log in migration history for specific errors
- Check if you’ve exceeded API quota
- Verify content isn’t too large (max ~8,000 tokens per item)
- Check for invalid characters in content
Pinecone Configuration
API Key
Found in your Pinecone dashboard under API Keys. Looks like: abc123-4567-89ab-cdef-0123456789ab
Host
Your index endpoint from Pinecone dashboard. Format: your-index-abc123.svc.pinecone.io
- ❌ Don’t include
https:// - ❌ Don’t use project URL
- ✅ Use the exact index host shown in dashboard
Namespace
Optional field. Leave empty for default namespace. Use specific namespaces to organize different datasets within the same index.
API Costs & Time Estimates
OpenAI Pricing (Approximate)
- Small blog (500 entries): ~$0.01
- Medium site (5,000 entries): ~$0.05
- Large site (50,000 entries): ~$0.50
Based on text-embedding-3-small pricing (~$0.0001 per 1K tokens)
Migration Time Estimates
Time depends on number of items, batch size, and API rate limits:
- 100 items: 2-3 minutes
- 1,000 items: 20-30 minutes
- 10,000 items: 3-5 hours
Pinecone Pricing
- Free tier: Up to 100K vectors
- Starter: $70/month for up to 5M vectors
Frequently Asked Questions
Do I need MxChat Pro?
Yes, an active MxChat Pro license is required to use the Migration Tool.
Will migration affect my live chatbot?
No, your chatbot continues working during migration with the current configuration. Settings only change if you choose to update them after completion.
How long does migration take?
Approximate times: 100 items (2-3 minutes), 1,000 items (20-30 minutes), 10,000 items (3-5 hours). Actual time varies based on batch size and API rate limits.
Can I cancel a migration?
Yes, click the Cancel button during migration. Note that partial progress may be saved depending on migration type and timing.
Should I migrate knowledge base and actions together?
Yes, recommended. This ensures consistent embedding space and proper automatic threshold adjustment for actions.
Which embedding model should I choose?
For most cases, use text-embedding-3-small (best quality-to-cost ratio). Use 3-large only if you need maximum quality and have the budget.
Do I need separate Pinecone indexes for different models?
Only if they have different dimensions. Models with 1536 dimensions (ada-002, 3-small, voyage-large-2, gemini) can share an index. Different dimensions require separate indexes.
Can I switch back to my old model?
Yes, simply run another migration back to the original model and database configuration.
What happens if my browser crashes during migration?
Migration stops immediately. You’ll need to start a new migration from the beginning. Always keep the browser tab open during migration.
Why do action thresholds change?
Different models produce different similarity scores. The plugin automatically adjusts thresholds based on empirical data to keep actions working correctly after migration.
Common Error Messages
“MxChat Basic required”
Solution: Install and activate the MxChat Basic plugin from your WordPress plugins page.
“Pro license required”
Solution: Activate your MxChat Pro license at MxChat → Activation. Verify the license is active and valid.
“Invalid API key”
Solution: Verify API key is correct for your selected model provider (OpenAI, Voyage AI, or Gemini). Check for extra spaces or incorrect characters.
“Rate limit exceeded”
Solution: Reduce batch size to 5 or lower and wait 60 seconds before retrying. You may be hitting API rate limits from your provider.
“Pinecone connection failed”
Solutions:
- Verify host format is correct (no https://)
- Check API key is correct in Pinecone dashboard
- Ensure index exists and is active in Pinecone
- Verify namespace matches if using custom namespace
“Failed to generate embedding”
Solutions:
- Check content isn’t too large (max ~8,000 tokens per item)
- Verify API key has sufficient quota remaining
- Check for invalid or special characters in content
- Try reducing batch size for more reliable processing
Need Help?
If you’re experiencing issues not covered here:
- Visit MxChat.ai for additional resources and documentation
- Check our YouTube channel for video tutorials
- Review the migration history table in the tool for detailed error logs
