donald/5why-analyzer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Add multi-LLM provider support with DeepSeek integration

Browse Source 
Major Features:
- ✨ Multi-LLM provider support (DeepSeek, Ollama, OpenAI, Custom)
- 🤖 Admin panel LLM configuration management UI
- 🔄 Dynamic provider switching without restart
- 🧪 Built-in API connection testing
- 🔒 Secure API key management

Backend Changes:
- Add routes/llmConfig.js: Complete LLM config CRUD API
- Update routes/analyze.js: Use database LLM configuration
- Update server.js: Add LLM config routes
- Add scripts/add-deepseek-config.js: DeepSeek setup script

Frontend Changes:
- Update src/pages/AdminPage.jsx: Add LLM Config tab + modal
- Update src/services/api.js: Add LLM config API methods
- Provider presets for DeepSeek, Ollama, OpenAI
- Test connection feature in config modal

Configuration:
- Update .env.example: Add DeepSeek API configuration
- Update package.json: Add llm:add-deepseek script

Documentation:
- Add docs/LLM_CONFIGURATION_GUIDE.md: Complete guide
- Add DEEPSEEK_INTEGRATION.md: Integration summary
- Quick setup instructions for DeepSeek

API Endpoints:
- GET /api/llm-config: List all configurations
- GET /api/llm-config/active: Get active configuration
- POST /api/llm-config: Create configuration
- PUT /api/llm-config/🆔 Update configuration
- PUT /api/llm-config/:id/activate: Activate configuration
- DELETE /api/llm-config/🆔 Delete configuration
- POST /api/llm-config/test: Test API connection

Database:
- Uses existing llm_configs table
- Only one config active at a time
- Fallback to Ollama if no database config

Security:
- Admin-only access to LLM configuration
- API keys never returned in GET requests
- Audit logging for all config changes
- Cannot delete active configuration

DeepSeek Model:
- Model: deepseek-chat
- High-quality 5 Why analysis
- Excellent Chinese language support
- Cost-effective pricing

🤖 Generated with Claude Code
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
donald
2025-12-06 00:33:10 +08:00
parent 30e39b5c6f
commit 957003bc7c
10 changed files with 1564 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

398
docs/LLM_CONFIGURATION_GUIDE.md Normal file
View File

@@ -0,0 +1,398 @@
# LLM Configuration Guide
## 📖 Overview
The 5 Why Root Cause Analyzer now supports multiple LLM providers! You can configure and switch between different AI models through the admin panel.
**Supported Providers:**
- ✅ **DeepSeek** (Recommended) - High quality, cost-effective
- ✅ **Ollama** - Self-hosted, privacy-focused
- ✅ **OpenAI** - Industry standard
- ✅ **Custom** - Any OpenAI-compatible API
---
## 🚀 Quick Start: DeepSeek Setup
### Step 1: Get DeepSeek API Key
1. Go to [https://platform.deepseek.com/](https://platform.deepseek.com/)
2. Sign up for an account
3. Navigate to **API Keys** section
4. Create a new API key
5. Copy the key (you won't be able to see it again!)
### Step 2: Add Configuration via Admin Panel
1. Login as admin or super_admin
2. Go to **管理者儀表板** (Admin Dashboard)
3. Click on **🤖 LLM 配置** tab
4. Click **➕ 新增配置** button
5. Fill in the form:
- **提供商**: Select "DeepSeek"
- **API 端點**: `https://api.deepseek.com`
- **API Key**: Paste your DeepSeek API key
- **模型名稱**: `deepseek-chat`
- **Temperature**: 0.7 (default)
- **Max Tokens**: 6000 (default)
- **Timeout**: 120 seconds (default)
6. Click **🔍 測試連線** to verify connection
7. Click **儲存** to save
8. Click **啟用** to activate this configuration
### Step 3: Start Using DeepSeek
That's it! All 5 Why analyses will now use DeepSeek API.
---
## 🔧 Configuration via Script
You can also add DeepSeek configuration using the command line:
### 1. Add API key to .env file:
```env
DEEPSEEK_API_KEY=your-api-key-here
DEEPSEEK_API_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat
```
### 2. Run the setup script:
```bash
npm run llm:add-deepseek
```
This will:
- Add DeepSeek configuration to the database
- Set it as the active LLM provider
- Deactivate all other providers
---
## 🎯 Using Different LLM Providers
### DeepSeek (Recommended)
**Pros:**
- High quality responses
- Cost-effective pricing
- Fast response times
- Excellent for Chinese language
**Configuration:**
```
Provider: DeepSeek
API Endpoint: https://api.deepseek.com
Model: deepseek-chat
API Key: Required
```
**Get API Key:** [https://platform.deepseek.com/](https://platform.deepseek.com/)
---
### Ollama (Self-Hosted)
**Pros:**
- Completely free
- Privacy-focused (runs locally or on your server)
- No API key required
- No rate limits
**Configuration:**
```
Provider: Ollama
API Endpoint: https://ollama_pjapi.theaken.com
Model: qwen2.5:3b
API Key: Not required
```
**Setup:** [https://ollama.ai/](https://ollama.ai/)
---
### OpenAI
**Pros:**
- Industry standard
- Most powerful models (GPT-4)
- Excellent documentation
- Multi-language support
**Configuration:**
```
Provider: OpenAI
API Endpoint: https://api.openai.com
Model: gpt-4 or gpt-3.5-turbo
API Key: Required
```
**Get API Key:** [https://platform.openai.com/](https://platform.openai.com/)
---
## ⚙️ Advanced Configuration
### Temperature
Controls randomness in responses:
- **0.0-0.3**: More focused and deterministic (good for technical analysis)
- **0.4-0.7**: Balanced (recommended for 5 Why analysis)
- **0.8-1.0**: More creative and varied
- **1.0+**: Very creative (not recommended)
**Recommended: 0.7**
### Max Tokens
Maximum length of the response:
- **2000**: Short responses
- **4000-6000**: Standard (recommended for 5 Why)
- **8000+**: Very detailed responses
**Recommended: 6000**
### Timeout
How long to wait for API response:
- **60 seconds**: Fast but may timeout on complex analysis
- **120 seconds**: Standard (recommended)
- **180+ seconds**: For very complex analyses
**Recommended: 120 seconds**
---
## 🔄 Switching Between Providers
You can have multiple LLM configurations and switch between them:
1. Go to **Admin Dashboard** > **LLM 配置**
2. View all configured providers
3. Click **啟用** on any provider to activate it
4. Only one provider can be active at a time
**Note:** You cannot delete the currently active provider.
---
## 🧪 Testing Configurations
Before saving a configuration, you can test the connection:
1. Fill in all required fields in the modal
2. Click **🔍 測試連線** button
3. Wait for the test to complete
4. If successful, you'll see "✅ 連線測試成功！"
5. If failed, check your API endpoint and key
---
## 📊 API Comparison
| Feature | DeepSeek | Ollama | OpenAI |
|---------|----------|--------|--------|
| **Cost** | $0.14/M tokens | Free | $3-60/M tokens |
| **Speed** | Fast | Medium | Fast |
| **Quality** | High | Good | Excellent |
| **Privacy** | Cloud | Private | Cloud |
| **Chinese** | Excellent | Good | Good |
| **API Key** | Required | No | Required |
| **Best For** | Production | Development | Enterprise |
---
## 🛠️ Troubleshooting
### "連線測試失敗"
**Possible causes:**
1. Invalid API key
2. Incorrect API endpoint
3. Network/firewall blocking request
4. API service is down
5. Rate limit exceeded
**Solutions:**
- Verify API key is correct
- Check API endpoint URL (no trailing slash)
- Test network connectivity: `curl https://api.deepseek.com`
- Check provider's status page
- Wait a few minutes if rate limited
### "Invalid response from API"
**Possible causes:**
1. Model name is incorrect
2. API format has changed
3. Response timeout
4. API returned an error
**Solutions:**
- Verify model name (e.g., `deepseek-chat`, not `deepseek`)
- Check provider's documentation
- Increase timeout seconds
- Check API logs for errors
### "Cannot delete active configuration"
**This is expected behavior.**
**Solution:**
- Activate a different configuration first
- Then delete the old one
---
## 🔒 Security Best Practices
### API Key Management
1. **Never commit API keys to git**
- Use .env file (already in .gitignore)
- Or use environment variables
- Or add via admin panel only
2. **Rotate keys regularly**
- Change API keys every 90 days
- Immediately rotate if compromised
3. **Use separate keys for dev/prod**
- Development: Use test/sandbox keys
- Production: Use production keys with limits
4. **Monitor usage**
- Set up billing alerts
- Track API usage
- Set rate limits
### Database Security
API keys are stored in the database:
- Ensure database has strong password
- Use SSL/TLS for database connections
- Regular backups
- Restrict database access
**Recommendation:** For production, encrypt API keys at rest using application-level encryption.
---
## 📝 API Endpoints
### Get All LLM Configs
```
GET /api/llm-config
```
Returns list of all LLM configurations (without API keys).
### Get Active Config
```
GET /api/llm-config/active
```
Returns the currently active LLM configuration.
### Create Config
```
POST /api/llm-config
Body: {
provider_name: string,
api_endpoint: string,
api_key: string (optional),
model_name: string,
temperature: number,
max_tokens: number,
timeout_seconds: number
}
```
### Update Config
```
PUT /api/llm-config/:id
Body: { ...same as create }
```
### Activate Config
```
PUT /api/llm-config/:id/activate
```
Deactivates all configs and activates the specified one.
### Delete Config
```
DELETE /api/llm-config/:id
```
Cannot delete active configuration.
### Test Config
```
POST /api/llm-config/test
Body: {
api_endpoint: string,
api_key: string (optional),
model_name: string
}
```
---
## 🎓 Example: Adding Custom Provider
Let's add Azure OpenAI as a custom provider:
1. Go to Admin Panel > LLM 配置
2. Click **➕ 新增配置**
3. Fill in:
```
Provider: Other
API Endpoint: https://your-resource.openai.azure.com
API Key: your-azure-api-key
Model: gpt-35-turbo
Temperature: 0.7
Max Tokens: 6000
Timeout: 120
```
4. Test connection
5. Save and activate
**Note:** The API must be OpenAI-compatible (use `/v1/chat/completions` endpoint).
---
## 🆘 Getting Help
### Official Documentation:
- **DeepSeek**: [https://platform.deepseek.com/docs](https://platform.deepseek.com/docs)
- **Ollama**: [https://ollama.ai/docs](https://ollama.ai/docs)
- **OpenAI**: [https://platform.openai.com/docs](https://platform.openai.com/docs)
### Project Documentation:
- [README.md](../README.md) - Project overview
- [API_DOC.md](./API_DOC.md) - API documentation
- [QUICKSTART.md](../QUICKSTART.md) - Getting started guide
### Repository:
https://gitea.theaken.com/donald/5why-analyzer
---
## 🎉 Success Checklist
Your LLM configuration is working correctly when:
- ✅ Test connection succeeds
- ✅ Configuration is marked as "啟用中" (Active)
- ✅ 5 Why analysis creates results without errors
- ✅ Analysis completes in reasonable time (<2 minutes)
- ✅ Results are high quality and in correct language
- ✅ No rate limit or quota errors
---
**Version**: 1.0.0
**Last Updated**: 2025-12-06
**Feature**: Multi-LLM Support
**Made with Claude Code** 🤖