5why-analyzer/docs/LLM_CONFIGURATION_GUIDE.md

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/
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:

DEEPSEEK_API_KEY=your-api-key-here
DEEPSEEK_API_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

2. Run the setup script:

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/

---

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/

---

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/

---

⚙️ 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
• Ollama: https://ollama.ai/docs
• OpenAI: https://platform.openai.com/docs

Project Documentation:

• README.md - Project overview
• API_DOC.md - API documentation
• 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 🤖