Add RAG client
This commit is contained in:
424
docs/rag-migration-guide.md
Normal file
424
docs/rag-migration-guide.md
Normal file
@@ -0,0 +1,424 @@
|
||||
# RAG Migration Guide
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains how to migrate from Dialogflow CX to the RAG (Retrieval-Augmented Generation) server for intent detection and response generation.
|
||||
|
||||
## Architecture
|
||||
|
||||
The integration layer now supports **both Dialogflow and RAG** implementations through a common interface (`IntentDetectionService`). You can switch between them using a configuration property.
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ ConversationManagerService / │
|
||||
│ NotificationManagerService │
|
||||
└────────────────┬────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────┐
|
||||
│ IntentDetectionService (interface) │
|
||||
└────────────┬────────────────────────────┘
|
||||
│
|
||||
┌──────┴──────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────┐ ┌──────────┐
|
||||
│Dialogflow│ │ RAG │
|
||||
│ Client │ │ Client │
|
||||
└──────────┘ └──────────┘
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Configure the RAG Server
|
||||
|
||||
Set the following environment variables:
|
||||
|
||||
```bash
|
||||
# Select RAG as the intent detection client
|
||||
export INTENT_DETECTION_CLIENT=rag
|
||||
|
||||
# RAG server URL
|
||||
export RAG_SERVER_URL=https://your-rag-server.com
|
||||
|
||||
# Optional: API key for authentication
|
||||
export RAG_SERVER_API_KEY=your-api-key-here
|
||||
|
||||
# Optional: Customize timeouts and retries (defaults shown)
|
||||
export RAG_SERVER_TIMEOUT=30s
|
||||
export RAG_SERVER_RETRY_MAX_ATTEMPTS=3
|
||||
export RAG_SERVER_RETRY_BACKOFF=1s
|
||||
```
|
||||
|
||||
### 2. Deploy and Test
|
||||
|
||||
Deploy the application with the new configuration:
|
||||
|
||||
```bash
|
||||
# Using Docker
|
||||
docker build -t capa-integracion:rag .
|
||||
docker run -e INTENT_DETECTION_CLIENT=rag \
|
||||
-e RAG_SERVER_URL=https://your-rag-server.com \
|
||||
capa-integracion:rag
|
||||
|
||||
# Or using Maven
|
||||
mvn spring-boot:run -Dspring-boot.run.profiles=dev
|
||||
```
|
||||
|
||||
### 3. Monitor Logs
|
||||
|
||||
On startup, you should see:
|
||||
|
||||
```
|
||||
✓ Intent detection configured to use RAG client
|
||||
RAG Client initialized successfully with endpoint: https://your-rag-server.com
|
||||
```
|
||||
|
||||
## Configuration Reference
|
||||
|
||||
### Intent Detection Selection
|
||||
|
||||
| Property | Values | Default | Description |
|
||||
|----------|--------|---------|-------------|
|
||||
| `intent.detection.client` | `dialogflow`, `rag` | `dialogflow` | Selects which implementation to use |
|
||||
|
||||
### RAG Server Configuration
|
||||
|
||||
| Property | Type | Default | Description |
|
||||
|----------|------|---------|-------------|
|
||||
| `rag.server.url` | URL | `http://localhost:8080` | RAG server base URL |
|
||||
| `rag.server.timeout` | Duration | `30s` | HTTP request timeout |
|
||||
| `rag.server.retry.max-attempts` | Integer | `3` | Maximum retry attempts on errors |
|
||||
| `rag.server.retry.backoff` | Duration | `1s` | Initial backoff duration for retries |
|
||||
| `rag.server.api-key` | String | (empty) | Optional API key for authentication |
|
||||
|
||||
### Dialogflow Configuration (Kept for Rollback)
|
||||
|
||||
These properties remain unchanged and are used when `intent.detection.client=dialogflow`:
|
||||
|
||||
```properties
|
||||
dialogflow.cx.project-id=${DIALOGFLOW_CX_PROJECT_ID}
|
||||
dialogflow.cx.location=${DIALOGFLOW_CX_LOCATION}
|
||||
dialogflow.cx.agent-id=${DIALOGFLOW_CX_AGENT_ID}
|
||||
dialogflow.default-language-code=${DIALOGFLOW_DEFAULT_LANGUAGE_CODE:es}
|
||||
```
|
||||
|
||||
## Switching Between Implementations
|
||||
|
||||
### Switch to RAG
|
||||
|
||||
```bash
|
||||
export INTENT_DETECTION_CLIENT=rag
|
||||
```
|
||||
|
||||
### Switch Back to Dialogflow
|
||||
|
||||
```bash
|
||||
export INTENT_DETECTION_CLIENT=dialogflow
|
||||
```
|
||||
|
||||
**No code changes required!** Just restart the application.
|
||||
|
||||
## What Stays the Same
|
||||
|
||||
✅ **External API contracts** - Controllers remain unchanged
|
||||
✅ **DTOs** - `DetectIntentRequestDTO` and `DetectIntentResponseDTO` unchanged
|
||||
✅ **Conversation storage** - Memorystore + Firestore persistence unchanged
|
||||
✅ **DLP obfuscation** - Data Loss Prevention flow unchanged
|
||||
✅ **Session management** - 30-minute timeout logic unchanged
|
||||
✅ **Notification handling** - Notification storage and retrieval unchanged
|
||||
|
||||
## What Changes
|
||||
|
||||
### RAG Receives:
|
||||
- Phone number (for internal conversation history tracking)
|
||||
- Obfuscated user input (already processed by DLP)
|
||||
- Notification context (when applicable)
|
||||
|
||||
### RAG Returns:
|
||||
- Response text (generated by RAG)
|
||||
- Response ID (for tracking)
|
||||
- Optional parameters (extracted/computed by RAG)
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Conversation Flow
|
||||
```
|
||||
User Message
|
||||
↓
|
||||
DLP Obfuscation
|
||||
↓
|
||||
ConversationManagerService
|
||||
↓
|
||||
IntentDetectionService (RAG or Dialogflow)
|
||||
↓
|
||||
RagRequestMapper → RAG Server → RagResponseMapper
|
||||
↓
|
||||
DetectIntentResponseDTO
|
||||
↓
|
||||
Persist to Memorystore + Firestore
|
||||
↓
|
||||
Response to User
|
||||
```
|
||||
|
||||
### Notification Flow
|
||||
```
|
||||
Notification Event
|
||||
↓
|
||||
DLP Obfuscation
|
||||
↓
|
||||
NotificationManagerService
|
||||
↓
|
||||
Store Notification (Memorystore + Firestore)
|
||||
↓
|
||||
IntentDetectionService (RAG or Dialogflow)
|
||||
↓
|
||||
RagRequestMapper → RAG Server → RagResponseMapper
|
||||
↓
|
||||
DetectIntentResponseDTO
|
||||
↓
|
||||
Response to User
|
||||
```
|
||||
|
||||
## Redundancy by Design
|
||||
|
||||
The integration layer intentionally maintains **redundant functionality** to ensure safe migration:
|
||||
|
||||
1. **Conversation History**
|
||||
- Integration layer: Continues to store history in Memorystore + Firestore
|
||||
- RAG server: Maintains its own history by phone number
|
||||
- **Why:** Allows gradual migration without data loss
|
||||
|
||||
2. **Session Management**
|
||||
- Integration layer: Continues to enforce 30-minute timeout
|
||||
- RAG server: Handles session internally by phone number
|
||||
- **Why:** Preserves existing business logic
|
||||
|
||||
3. **Parameter Passing**
|
||||
- Integration layer: Continues to extract and pass all parameters
|
||||
- RAG server: Uses only what it needs (phone number, text, notifications)
|
||||
- **Why:** Maintains flexibility for future requirements
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### RAG Server Not Responding
|
||||
|
||||
**Symptom:** Errors like "RAG connection failed" or "RAG request timeout"
|
||||
|
||||
**Solution:**
|
||||
1. Verify `RAG_SERVER_URL` is correct
|
||||
2. Check RAG server is running and accessible
|
||||
3. Verify network connectivity
|
||||
4. Check RAG server logs for errors
|
||||
5. Temporarily switch back to Dialogflow:
|
||||
```bash
|
||||
export INTENT_DETECTION_CLIENT=dialogflow
|
||||
```
|
||||
|
||||
### Invalid RAG Response Format
|
||||
|
||||
**Symptom:** Errors like "Failed to parse RAG response"
|
||||
|
||||
**Solution:**
|
||||
1. Verify RAG server implements the API specification (see `docs/rag-api-specification.md`)
|
||||
2. Check RAG server response format matches expected structure
|
||||
3. Review `RagResponseMapper` logs for specific parsing errors
|
||||
|
||||
### Missing Phone Number
|
||||
|
||||
**Symptom:** Error "Phone number is required in request parameters"
|
||||
|
||||
**Solution:**
|
||||
1. Verify external requests include phone number in user data
|
||||
2. Check `ExternalConvRequestMapper` correctly maps phone number to `telefono` parameter
|
||||
|
||||
### Dialogflow Fallback Issues
|
||||
|
||||
**Symptom:** After switching back to Dialogflow, errors occur
|
||||
|
||||
**Solution:**
|
||||
1. Verify all Dialogflow environment variables are still set:
|
||||
- `DIALOGFLOW_CX_PROJECT_ID`
|
||||
- `DIALOGFLOW_CX_LOCATION`
|
||||
- `DIALOGFLOW_CX_AGENT_ID`
|
||||
2. Check Dialogflow credentials are valid
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
If issues arise with RAG, immediately rollback:
|
||||
|
||||
### Step 1: Switch Configuration
|
||||
```bash
|
||||
export INTENT_DETECTION_CLIENT=dialogflow
|
||||
```
|
||||
|
||||
### Step 2: Restart Application
|
||||
```bash
|
||||
# Docker
|
||||
docker restart <container-id>
|
||||
|
||||
# Kubernetes
|
||||
kubectl rollout restart deployment/capa-integracion
|
||||
```
|
||||
|
||||
### Step 3: Verify
|
||||
Check logs for:
|
||||
```
|
||||
✓ Intent detection configured to use Dialogflow CX client
|
||||
Dialogflow CX SessionsClient initialized successfully
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Key Metrics to Monitor
|
||||
|
||||
1. **Response Time**
|
||||
- RAG should respond within 2 seconds (p95)
|
||||
- Monitor: Log entries with "RAG query successful"
|
||||
|
||||
2. **Error Rate**
|
||||
- Target: < 0.5% error rate
|
||||
- Monitor: Log entries with "RAG query failed"
|
||||
|
||||
3. **Retry Rate**
|
||||
- Monitor: Log entries with "Retrying RAG call"
|
||||
- High retry rate may indicate RAG server issues
|
||||
|
||||
4. **Response Quality**
|
||||
- Monitor user satisfaction or conversation completion rates
|
||||
- Compare before/after RAG migration
|
||||
|
||||
### Log Patterns
|
||||
|
||||
**Successful RAG Call:**
|
||||
```
|
||||
INFO Initiating RAG query for session: <session-id>
|
||||
DEBUG Successfully mapped request to RAG format
|
||||
INFO RAG query successful for session: <session-id>, response ID: <response-id>
|
||||
```
|
||||
|
||||
**Failed RAG Call:**
|
||||
```
|
||||
ERROR RAG server error for session <session-id>: status=500
|
||||
WARN Retrying RAG call for session <session-id> due to status code: 500
|
||||
ERROR RAG retries exhausted for session <session-id>
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
### Manual Testing
|
||||
|
||||
1. **Test Regular Conversation**
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/dialogflow/detect-intent \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"message": "¿Cuál es el estado de mi solicitud?",
|
||||
"user": {
|
||||
"telefono": "573001234567",
|
||||
"nickname": "TestUser"
|
||||
},
|
||||
"channel": "web",
|
||||
"tipo": "text"
|
||||
}'
|
||||
```
|
||||
|
||||
2. **Test Notification Flow**
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/dialogflow/notification \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"text": "Tu documento ha sido aprobado",
|
||||
"phoneNumber": "573001234567",
|
||||
"hiddenParameters": {
|
||||
"document_id": "DOC-2025-001"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
### Expected Behavior
|
||||
|
||||
- RAG should return relevant responses based on conversation context
|
||||
- Response time should be similar to or better than Dialogflow
|
||||
- All parameters should be preserved in conversation history
|
||||
- Notification context should be used in RAG responses
|
||||
|
||||
## Migration Phases (Recommended)
|
||||
|
||||
### Phase 1: Development Testing (1 week)
|
||||
- Deploy RAG to dev environment
|
||||
- Set `INTENT_DETECTION_CLIENT=rag`
|
||||
- Test all conversation flows manually
|
||||
- Verify notification handling
|
||||
|
||||
### Phase 2: QA Environment (1 week)
|
||||
- Deploy to QA with RAG enabled
|
||||
- Run automated test suite
|
||||
- Perform load testing
|
||||
- Compare responses with Dialogflow baseline
|
||||
|
||||
### Phase 3: Production Pilot (1-2 weeks)
|
||||
- Deploy to production with `INTENT_DETECTION_CLIENT=dialogflow` (Dialogflow still active)
|
||||
- Gradually switch to RAG:
|
||||
- Week 1: 10% of traffic
|
||||
- Week 2: 50% of traffic
|
||||
- Week 3: 100% of traffic
|
||||
- Monitor metrics closely
|
||||
|
||||
### Phase 4: Full Migration
|
||||
- Set `INTENT_DETECTION_CLIENT=rag` for all environments
|
||||
- Keep Dialogflow config for potential rollback
|
||||
- Monitor for 2 weeks before considering removal of Dialogflow dependencies
|
||||
|
||||
## Future Cleanup (Optional)
|
||||
|
||||
After RAG is stable in production for 1+ month:
|
||||
|
||||
### Phase 1: Deprecate Dialogflow
|
||||
1. Add `@Deprecated` annotation to `DialogflowClientService`
|
||||
2. Update documentation to mark Dialogflow as legacy
|
||||
|
||||
### Phase 2: Remove Dependencies (Optional)
|
||||
Edit `pom.xml` and remove:
|
||||
```xml
|
||||
<!-- Can be removed after RAG is stable -->
|
||||
<!--
|
||||
<dependency>
|
||||
<groupId>com.google.cloud</groupId>
|
||||
<artifactId>google-cloud-dialogflow-cx</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.google.protobuf</groupId>
|
||||
<artifactId>protobuf-java-util</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>com.google.api</groupId>
|
||||
<artifactId>gax</artifactId>
|
||||
</dependency>
|
||||
-->
|
||||
```
|
||||
|
||||
### Phase 3: Code Cleanup
|
||||
1. Remove `DialogflowClientService.java`
|
||||
2. Remove `DialogflowRequestMapper.java`
|
||||
3. Remove `DialogflowResponseMapper.java`
|
||||
4. Remove Dialogflow-specific tests
|
||||
5. Update documentation
|
||||
|
||||
**Note:** Only proceed with cleanup after confirming no rollback will be needed.
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check this guide and `docs/rag-api-specification.md`
|
||||
2. Review application logs
|
||||
3. Contact the RAG server team for API issues
|
||||
4. Contact the integration layer team for mapping/configuration issues
|
||||
|
||||
## Summary
|
||||
|
||||
- **Minimal Code Changes:** Only configuration needed to switch
|
||||
- **Safe Rollback:** Can switch back to Dialogflow instantly
|
||||
- **Redundancy:** Both systems store data for safety
|
||||
- **Gradual Migration:** Supports phased rollout
|
||||
- **No External Impact:** API contracts unchanged
|
||||
Reference in New Issue
Block a user