rckrdmrd
97f407c661
- Prefijo v2: MCH - TRACEABILITY-MASTER.yml creado - Listo para integracion como submodulo Workspace: v2.0.0 | SIMCO: v4.0.0
162 lines
6.9 KiB
Markdown
162 lines
6.9 KiB
Markdown
---
|
|
id: INT-009
|
|
type: Integration
|
|
title: "Transcripción de audio"
|
|
provider: "OpenAI Whisper"
|
|
status: Pendiente
|
|
integration_type: "Speech-to-Text"
|
|
created_at: 2026-01-10
|
|
updated_at: 2026-01-10
|
|
simco_version: "3.8.0"
|
|
tags:
|
|
- audio
|
|
- transcripcion
|
|
- whisper
|
|
- openai
|
|
- speech-to-text
|
|
- whatsapp
|
|
---
|
|
|
|
# INT-009: Transcripción de audio
|
|
|
|
## Metadata
|
|
|
|
| Campo | Valor |
|
|
|-------|-------|
|
|
| **Codigo** | INT-009 |
|
|
| **Proveedor** | OpenAI Whisper |
|
|
| **Tipo** | Speech-to-Text |
|
|
| **Estado** | Pendiente |
|
|
| **Multi-tenant** | Si |
|
|
| **Fecha planeada** | 2026-Q1 |
|
|
| **Owner** | Backend Team |
|
|
|
|
---
|
|
|
|
## 1. Descripcion
|
|
|
|
Integración con OpenAI Whisper API para transcripción automática de mensajes de voz. Permite convertir los audios recibidos por WhatsApp en texto, facilitando el procesamiento automático de pedidos por voz y mejorando la experiencia del cliente que prefiere enviar notas de voz en lugar de escribir.
|
|
|
|
**Casos de uso principales:**
|
|
- Transcripción de mensajes de voz de WhatsApp de clientes
|
|
- Procesamiento de pedidos dictados por voz
|
|
- Generación de registros de conversaciones por audio
|
|
- Búsqueda de contenido en mensajes de voz históricos
|
|
- Accesibilidad para usuarios con dificultades de lectura
|
|
|
|
---
|
|
|
|
## 2. Credenciales Requeridas
|
|
|
|
### Variables de Entorno
|
|
|
|
| Variable | Descripcion | Tipo | Obligatorio |
|
|
|----------|-------------|------|-------------|
|
|
| OPENAI_API_KEY | API key de OpenAI | string | SI |
|
|
| WHISPER_MODEL | Modelo a usar (whisper-1) | string | SI |
|
|
| WHISPER_LANGUAGE | Idioma por defecto (es) | string | NO |
|
|
| WHISPER_RESPONSE_FORMAT | Formato de respuesta (json, text, srt, vtt) | string | NO |
|
|
| OPENAI_ORG_ID | ID de organización OpenAI (opcional) | string | NO |
|
|
|
|
### Ejemplo de .env
|
|
|
|
```env
|
|
# OpenAI Whisper Transcription
|
|
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
|
|
WHISPER_MODEL=whisper-1
|
|
WHISPER_LANGUAGE=es
|
|
WHISPER_RESPONSE_FORMAT=json
|
|
OPENAI_ORG_ID=org-xxxxxxxxxxxxxxxx
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Arquitectura
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ MiChangarrito │
|
|
│ ┌────────────────┐ ┌──────────────┐ ┌────────────────────────┐ │
|
|
│ │ WhatsApp │───▶│ Message │───▶│ WhisperService │ │
|
|
│ │ Webhook │ │ Processor │ │ │ │
|
|
│ │ (Audio msg) │ │ │ │ - Download audio │ │
|
|
│ └────────────────┘ └──────────────┘ │ - Convert format │ │
|
|
│ │ - Transcribe │ │
|
|
│ │ - Parse intent │ │
|
|
│ └───────────┬────────────┘ │
|
|
└────────────────────────────────────────────────────────┼───────────────┘
|
|
│
|
|
┌─────────────────────────┴─────────────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌──────────────────┐ ┌──────────────────┐
|
|
│ OpenAI API │ │ LLM Service │
|
|
│ Whisper │ │ (Intent/NER) │
|
|
│ │ │ │
|
|
│ Audio → Texto │ │ Texto → Pedido │
|
|
└──────────────────┘ └──────────────────┘
|
|
```
|
|
|
|
### Flujo de Procesamiento de Audio
|
|
|
|
1. Cliente envía nota de voz por WhatsApp
|
|
2. Webhook recibe mensaje con media_id del audio
|
|
3. Sistema descarga archivo de audio de WhatsApp
|
|
4. Audio se convierte a formato compatible (mp3/wav)
|
|
5. WhisperService envía audio a OpenAI Whisper API
|
|
6. API retorna transcripción en español
|
|
7. Texto se procesa con LLM para extraer intención
|
|
8. Si es pedido, se extrae productos y cantidades
|
|
9. Se responde al cliente confirmando pedido
|
|
|
|
---
|
|
|
|
## 4. Endpoints
|
|
|
|
### Endpoints Consumidos (OpenAI Whisper API)
|
|
|
|
| Método | Endpoint | Descripción |
|
|
|--------|----------|-------------|
|
|
| POST | `/v1/audio/transcriptions` | Transcribir audio a texto |
|
|
| POST | `/v1/audio/translations` | Transcribir y traducir a inglés |
|
|
|
|
### Parámetros de Request
|
|
|
|
| Parámetro | Tipo | Descripción |
|
|
|-----------|------|-------------|
|
|
| `file` | file | Archivo de audio (mp3, wav, m4a, etc.) |
|
|
| `model` | string | Modelo: "whisper-1" |
|
|
| `language` | string | Código ISO-639-1 (ej: "es") |
|
|
| `response_format` | string | json, text, srt, verbose_json, vtt |
|
|
| `temperature` | float | 0-1, mayor = más creativo |
|
|
| `prompt` | string | Contexto para mejorar precisión |
|
|
|
|
### Endpoints Expuestos (MiChangarrito)
|
|
|
|
| Método | Endpoint | Descripción |
|
|
|--------|----------|-------------|
|
|
| POST | `/api/v1/audio/transcribe` | Transcribir audio subido |
|
|
| POST | `/api/v1/audio/transcribe-url` | Transcribir desde URL |
|
|
| GET | `/api/v1/audio/transcriptions/{id}` | Obtener transcripción |
|
|
| GET | `/api/v1/audio/transcriptions` | Listar transcripciones |
|
|
|
|
---
|
|
|
|
## 5. Notas de Implementacion
|
|
|
|
- Whisper soporta: mp3, mp4, mpeg, mpga, m4a, wav, webm
|
|
- Tamaño máximo de archivo: 25MB
|
|
- Para audios largos, segmentar en chunks de ~10 minutos
|
|
- Usar `language: "es"` para mejor precisión en español mexicano
|
|
- El prompt puede incluir términos del dominio (productos del changarro)
|
|
- Costo aproximado: $0.006 USD por minuto de audio
|
|
- Implementar cola para procesar audios en background
|
|
- Guardar transcripciones para evitar reprocesar
|
|
- WhatsApp envía audios en formato OGG/Opus, convertir a mp3
|
|
- Usar ffmpeg para conversión de formatos
|
|
- Implementar fallback si Whisper falla (mensaje de error al usuario)
|
|
- Considerar modelo Whisper local para reducir costos a largo plazo
|
|
- Manejar rate limits: 50 RPM para whisper-1
|
|
- La transcripción incluye timestamps en formato verbose_json
|
|
- Implementar detección de idioma automática para clientes no hispanohablantes
|