se agrega .md de tailscale para hacer gitea https
This commit is contained in:
George committed
1 parent
f915802fb4
commit
920a4a2d56
10 files changed
+2081
-2066
No files matched your search
@@ -0,0 +1,674 @@
|
||||
# Agente IA para SAP Business One + HANA
|
||||
|
||||
## Objetivo
|
||||
|
||||
Construir progresivamente un agente de IA tipo chat para la empresa, conectado a SAP Business One sobre HANA, usando modelos locales mediante Ollama.
|
||||
|
||||
La evolución prevista es:
|
||||
|
||||
- Consultas de negocio en lenguaje natural.
|
||||
- KPIs.
|
||||
- Análisis de datos.
|
||||
- Gráficos y cuadros resumen.
|
||||
- Reportes PDF y Excel.
|
||||
- Resúmenes gerenciales.
|
||||
- Alertas y análisis automáticos.
|
||||
|
||||
La estrategia es comenzar pequeño y agregar capacidades mediante herramientas independientes.
|
||||
|
||||
## Arquitectura
|
||||
|
||||
```text
|
||||
USUARIO
|
||||
|
|
||||
v
|
||||
+-------------+
|
||||
| Chat Web UI |
|
||||
| React/Vite |
|
||||
+------+------+
|
||||
|
|
||||
v
|
||||
+-------------+
|
||||
| FastAPI |
|
||||
| Backend |
|
||||
+------+------+
|
||||
|
|
||||
+---------+---------+
|
||||
| |
|
||||
v v
|
||||
+-----------+ +--------------+
|
||||
| Ollama | | Tool / Skill |
|
||||
| Local LLM | | Engine |
|
||||
+-----------+ +-------+------+
|
||||
|
|
||||
+--------+--------+
|
||||
| |
|
||||
v v
|
||||
SAP HANA SAP Service Layer
|
||||
```
|
||||
|
||||
### Principio fundamental
|
||||
|
||||
El modelo de IA no debe tener acceso directo e irrestricto a SAP.
|
||||
|
||||
El LLM debe solicitar herramientas (`tools`) que ejecuten consultas controladas.
|
||||
|
||||
Ejemplo:
|
||||
|
||||
```text
|
||||
Usuario: ¿Cuánto vendimos este mes?
|
||||
|
|
||||
v
|
||||
Ollama
|
||||
|
|
||||
v
|
||||
ventas_mes()
|
||||
|
|
||||
v
|
||||
Python / FastAPI
|
||||
|
|
||||
v
|
||||
SAP HANA
|
||||
|
|
||||
v
|
||||
Resultado
|
||||
|
|
||||
v
|
||||
Ollama
|
||||
|
|
||||
v
|
||||
Respuesta al usuario
|
||||
```
|
||||
|
||||
Esto permite controlar permisos, consultas y calidad de los resultados.
|
||||
|
||||
## Tecnologías
|
||||
|
||||
### Frontend
|
||||
- React
|
||||
- Vite
|
||||
- Interfaz tipo ChatGPT
|
||||
- Tablas
|
||||
- Gráficos
|
||||
- Dashboards
|
||||
|
||||
### Backend
|
||||
- Python
|
||||
- FastAPI
|
||||
- Herramientas / Skills
|
||||
- Control de acceso
|
||||
- Gestión de conversaciones
|
||||
- Generación de reportes
|
||||
|
||||
### IA
|
||||
- Ollama
|
||||
- Modelos locales
|
||||
- Candidatos iniciales: Qwen 3 8B, Qwen 3 14B, Mistral Small y Gemma 3 12B.
|
||||
- La elección final dependerá del hardware y de pruebas reales.
|
||||
|
||||
### Datos e integración
|
||||
- SAP Business One
|
||||
- SAP HANA
|
||||
- Vistas HANA
|
||||
- SQL controlado
|
||||
- SAP Service Layer para operaciones que necesiten la lógica de SAP
|
||||
|
||||
### Visualización y documentos
|
||||
- Plotly para gráficos interactivos
|
||||
- Matplotlib para imágenes/gráficos destinados a documentos
|
||||
- ReportLab para PDF
|
||||
- OpenPyXL para Excel
|
||||
|
||||
# Fase 1: herramientas básicas
|
||||
|
||||
Crear inicialmente un conjunto pequeño de funciones Python:
|
||||
|
||||
```text
|
||||
ventas_hoy()
|
||||
ventas_mes()
|
||||
top_clientes()
|
||||
productos_mas_vendidos()
|
||||
facturas_pendientes()
|
||||
compras_mes()
|
||||
stock_critico()
|
||||
cuentas_por_cobrar()
|
||||
cuentas_por_pagar()
|
||||
utilidad_mes()
|
||||
```
|
||||
|
||||
Cada herramienta ejecutará internamente una consulta SQL o utilizará una vista HANA.
|
||||
|
||||
El usuario pregunta:
|
||||
|
||||
```text
|
||||
¿Cuánto vendimos este mes?
|
||||
```
|
||||
|
||||
El agente determina:
|
||||
|
||||
```text
|
||||
tool = ventas_mes()
|
||||
```
|
||||
|
||||
Obtiene el resultado y genera una respuesta en lenguaje natural.
|
||||
|
||||
## Fase 2: herramientas con parámetros
|
||||
|
||||
Agregar parámetros:
|
||||
|
||||
```text
|
||||
ventas_por_cliente(cliente)
|
||||
ventas_por_fecha(desde, hasta)
|
||||
compras_por_proveedor(proveedor, desde, hasta)
|
||||
stock_almacen(almacen)
|
||||
articulo(codigo)
|
||||
```
|
||||
|
||||
Ejemplo:
|
||||
|
||||
```text
|
||||
¿Cuánto le hemos vendido a Alicorp este año?
|
||||
```
|
||||
|
||||
Puede interpretarse como:
|
||||
|
||||
```text
|
||||
ventas_cliente(
|
||||
cliente="ALICORP",
|
||||
año=2026
|
||||
)
|
||||
```
|
||||
|
||||
## Fase 3: capa semántica empresarial
|
||||
|
||||
En lugar de hacer que el modelo conozca todas las tablas de SAP Business One, crear vistas orientadas al negocio:
|
||||
|
||||
```text
|
||||
VW_VENTAS
|
||||
VW_COMPRAS
|
||||
VW_STOCK
|
||||
VW_CXC
|
||||
VW_CXP
|
||||
VW_CLIENTES
|
||||
VW_PRODUCTOS
|
||||
VW_VENDEDORES
|
||||
VW_KPI_VENTAS
|
||||
VW_KPI_COBRANZAS
|
||||
```
|
||||
|
||||
Las vistas deben presentar información clara y consistente, por ejemplo:
|
||||
|
||||
```text
|
||||
Cliente
|
||||
RUC
|
||||
Vendedor
|
||||
Línea
|
||||
Ciudad
|
||||
Total
|
||||
Margen
|
||||
Cantidad
|
||||
Fecha
|
||||
```
|
||||
|
||||
## Fase 4: SQL generado por IA
|
||||
|
||||
Cuando el sistema básico sea estable, se puede permitir que el modelo genere SQL, pero únicamente sobre vistas analíticas autorizadas.
|
||||
|
||||
Ejemplo:
|
||||
|
||||
```text
|
||||
Vista: VW_VENTAS
|
||||
|
||||
Campos:
|
||||
Fecha
|
||||
Cliente
|
||||
Ciudad
|
||||
Total
|
||||
Margen
|
||||
Cantidad
|
||||
Vendedor
|
||||
```
|
||||
|
||||
Pregunta:
|
||||
|
||||
```text
|
||||
¿Cuánto vendimos por ciudad?
|
||||
```
|
||||
|
||||
Consulta posible:
|
||||
|
||||
```sql
|
||||
SELECT
|
||||
Ciudad,
|
||||
SUM(Total) AS TotalVentas
|
||||
FROM VW_VENTAS
|
||||
GROUP BY Ciudad;
|
||||
```
|
||||
|
||||
El backend debe validar el SQL antes de ejecutarlo.
|
||||
|
||||
## Fase 5: conversación con contexto
|
||||
|
||||
El agente debe mantener el contexto:
|
||||
|
||||
```text
|
||||
Usuario: Muéstrame las ventas de marzo.
|
||||
Agente: ...
|
||||
|
||||
Usuario: Ahora solo Lima.
|
||||
Agente: ...
|
||||
|
||||
Usuario: Compáralo con febrero.
|
||||
Agente: ...
|
||||
|
||||
Usuario: Haz un gráfico.
|
||||
Agente: ...
|
||||
```
|
||||
|
||||
## Fase 6: gráficos
|
||||
|
||||
El agente podrá generar visualizaciones como:
|
||||
|
||||
- Ventas por vendedor
|
||||
- Ventas por ciudad
|
||||
- Ventas mensuales
|
||||
- Margen por línea
|
||||
- Top 10 productos
|
||||
- Top 10 clientes
|
||||
- Evolución de cobranza
|
||||
- Stock por almacén
|
||||
|
||||
Flujo:
|
||||
|
||||
```text
|
||||
Pregunta -> Tool -> HANA -> Datos -> Motor de gráficos -> Gráfico -> Chat
|
||||
```
|
||||
|
||||
## Fase 7: KPIs
|
||||
|
||||
Crear un catálogo de indicadores.
|
||||
|
||||
### Ventas
|
||||
- Ventas del mes
|
||||
- Ventas acumuladas
|
||||
- Cumplimiento de meta
|
||||
- Crecimiento vs. período anterior
|
||||
- Ticket promedio
|
||||
- Ventas por vendedor
|
||||
- Ventas por cliente
|
||||
- Ventas por producto
|
||||
|
||||
### Rentabilidad
|
||||
- Margen bruto
|
||||
- Margen por producto
|
||||
- Margen por línea
|
||||
- Margen por vendedor
|
||||
|
||||
### Inventario
|
||||
- Stock disponible
|
||||
- Stock crítico
|
||||
- Rotación
|
||||
- Productos sin movimiento
|
||||
- Productos próximos a agotarse
|
||||
|
||||
### Finanzas
|
||||
- Cuentas por cobrar
|
||||
- Cuentas por pagar
|
||||
- Vencimientos
|
||||
- Cobranza
|
||||
- Antigüedad de saldos
|
||||
|
||||
## Fase 8: reportes
|
||||
|
||||
El usuario podrá solicitar:
|
||||
|
||||
```text
|
||||
Genera un resumen gerencial de junio.
|
||||
```
|
||||
|
||||
El sistema:
|
||||
|
||||
1. Consulta los datos.
|
||||
2. Calcula KPIs.
|
||||
3. Genera gráficos.
|
||||
4. Utiliza el LLM para interpretar los resultados.
|
||||
5. Genera conclusiones.
|
||||
6. Crea un PDF.
|
||||
7. Puede crear un Excel.
|
||||
|
||||
Estructura posible:
|
||||
|
||||
```text
|
||||
REPORTE GERENCIAL
|
||||
|
||||
Resumen ejecutivo
|
||||
Ventas
|
||||
Rentabilidad
|
||||
Inventario
|
||||
Cuentas por cobrar
|
||||
Principales variaciones
|
||||
Principales clientes
|
||||
Principales productos
|
||||
Conclusiones
|
||||
```
|
||||
|
||||
## Fase 9: alertas automáticas
|
||||
|
||||
Ejemplo de resumen diario:
|
||||
|
||||
```text
|
||||
Ventas: S/ 124,500
|
||||
Meta: 95%
|
||||
Margen: 28%
|
||||
|
||||
Top vendedor: Carlos
|
||||
Productos sin stock: 14
|
||||
Clientes con deuda: 18
|
||||
```
|
||||
|
||||
El agente también podría detectar anomalías:
|
||||
|
||||
```text
|
||||
- Las ventas de Arequipa disminuyeron 15%.
|
||||
- El producto X cayó 20% respecto al promedio.
|
||||
- Las cobranzas aumentaron 12%.
|
||||
- Tres clientes concentran una parte importante de la deuda vencida.
|
||||
```
|
||||
|
||||
La IA debe aportar principalmente interpretación de datos reales, no inventar respuestas plausibles.
|
||||
|
||||
## Seguridad
|
||||
|
||||
Principios desde el inicio:
|
||||
|
||||
- El LLM no debe tener credenciales directas de HANA.
|
||||
- Las herramientas deben estar controladas por el backend.
|
||||
- Separar consultas de lectura de operaciones de escritura.
|
||||
- No permitir SQL arbitrario inicialmente.
|
||||
- Validar parámetros.
|
||||
- Registrar las consultas ejecutadas.
|
||||
- Registrar usuario, herramienta y fecha.
|
||||
- Controlar qué herramientas puede utilizar cada usuario.
|
||||
- Utilizar Service Layer para operaciones que modifiquen SAP.
|
||||
- No permitir que una pregunta de lenguaje natural ejecute operaciones destructivas.
|
||||
|
||||
Arquitectura de lectura:
|
||||
|
||||
```text
|
||||
Usuario -> LLM -> Tool controlada -> Vista/Query HANA -> Resultado
|
||||
```
|
||||
|
||||
Arquitectura de operaciones:
|
||||
|
||||
```text
|
||||
Usuario -> LLM -> Tool controlada -> Validación -> Service Layer -> SAP Business One
|
||||
```
|
||||
|
||||
# Capa semántica empresarial
|
||||
|
||||
Uno de los componentes más importantes será un catálogo que explique al agente qué significa cada dato.
|
||||
|
||||
Ejemplo:
|
||||
|
||||
```text
|
||||
VW_VENTAS
|
||||
|
||||
Descripción:
|
||||
Información consolidada de documentos de venta.
|
||||
|
||||
Campos:
|
||||
|
||||
Fecha
|
||||
Fecha del documento.
|
||||
|
||||
Cliente
|
||||
Código del cliente.
|
||||
|
||||
NombreCliente
|
||||
Nombre comercial.
|
||||
|
||||
Vendedor
|
||||
Vendedor responsable.
|
||||
|
||||
Total
|
||||
Importe total del documento.
|
||||
|
||||
Margen
|
||||
Margen bruto calculado.
|
||||
|
||||
Cantidad
|
||||
Cantidad vendida.
|
||||
```
|
||||
|
||||
También se deben documentar reglas de negocio, por ejemplo:
|
||||
|
||||
```text
|
||||
"Ventas" significa documentos de venta contabilizados.
|
||||
|
||||
"No considerar documentos cancelados."
|
||||
|
||||
"Margen" se calcula utilizando el costo correspondiente.
|
||||
|
||||
"Ventas del mes" utiliza DocDate salvo que se indique otra fecha.
|
||||
```
|
||||
|
||||
Esto será más importante que intentar meter miles de tablas SAP en el contexto del LLM.
|
||||
|
||||
# Estructura inicial del proyecto
|
||||
|
||||
```text
|
||||
agente_sap/
|
||||
|
|
||||
+-- app/
|
||||
| +-- main.py
|
||||
| +-- api/
|
||||
| | +-- chat.py
|
||||
| | +-- reports.py
|
||||
| +-- agent/
|
||||
| | +-- agent.py
|
||||
| | +-- prompts.py
|
||||
| | +-- tools.py
|
||||
| +-- tools/
|
||||
| | +-- ventas.py
|
||||
| | +-- compras.py
|
||||
| | +-- stock.py
|
||||
| | +-- clientes.py
|
||||
| | +-- finanzas.py
|
||||
| +-- database/
|
||||
| | +-- hana.py
|
||||
| +-- sap/
|
||||
| | +-- service_layer.py
|
||||
| +-- reports/
|
||||
| | +-- pdf.py
|
||||
| | +-- excel.py
|
||||
| +-- charts/
|
||||
| +-- charts.py
|
||||
|
|
||||
+-- frontend/
|
||||
| +-- ...
|
||||
|
|
||||
+-- sql/
|
||||
| +-- views/
|
||||
| +-- queries/
|
||||
|
|
||||
+-- docs/
|
||||
| +-- semantic_layer/
|
||||
|
|
||||
+-- tests/
|
||||
|
|
||||
+-- .env
|
||||
+-- requirements.txt
|
||||
+-- README.md
|
||||
```
|
||||
|
||||
# Primera versión recomendada
|
||||
|
||||
No empezar con dashboards, agentes autónomos ni SQL generado por IA.
|
||||
|
||||
La primera versión debería hacer solamente:
|
||||
|
||||
```text
|
||||
Chat
|
||||
|
|
||||
v
|
||||
Ollama
|
||||
|
|
||||
v
|
||||
Tools Python
|
||||
|
|
||||
v
|
||||
HANA
|
||||
|
|
||||
v
|
||||
Resultado
|
||||
|
|
||||
v
|
||||
Ollama
|
||||
|
|
||||
v
|
||||
Respuesta
|
||||
```
|
||||
|
||||
Con cinco herramientas iniciales:
|
||||
|
||||
```text
|
||||
ventas_hoy()
|
||||
ventas_mes()
|
||||
top_clientes()
|
||||
stock_critico()
|
||||
cuentas_por_cobrar()
|
||||
```
|
||||
|
||||
Y una interfaz web sencilla.
|
||||
|
||||
# Evolución recomendada
|
||||
|
||||
```text
|
||||
FASE 1
|
||||
Chat + Ollama + 5 tools
|
||||
|
|
||||
v
|
||||
FASE 2
|
||||
Tools con parámetros
|
||||
|
|
||||
v
|
||||
FASE 3
|
||||
Vistas HANA / capa semántica
|
||||
|
|
||||
v
|
||||
FASE 4
|
||||
SQL controlado sobre vistas
|
||||
|
|
||||
v
|
||||
FASE 5
|
||||
Contexto conversacional
|
||||
|
|
||||
v
|
||||
FASE 6
|
||||
Gráficos
|
||||
|
|
||||
v
|
||||
FASE 7
|
||||
KPIs
|
||||
|
|
||||
v
|
||||
FASE 8
|
||||
PDF / Excel
|
||||
|
|
||||
v
|
||||
FASE 9
|
||||
Dashboards
|
||||
|
|
||||
v
|
||||
FASE 10
|
||||
Alertas y análisis automáticos
|
||||
```
|
||||
|
||||
# Objetivo final
|
||||
|
||||
El asistente podrá responder preguntas como:
|
||||
|
||||
```text
|
||||
¿Cuánto vendimos este mes?
|
||||
|
||||
¿Cuáles son nuestros 10 mejores clientes?
|
||||
|
||||
¿Qué productos están cayendo en ventas?
|
||||
|
||||
¿Qué vendedores no están alcanzando su meta?
|
||||
|
||||
¿Cuánto tenemos pendiente de cobrar?
|
||||
|
||||
¿Qué clientes tienen mayor deuda vencida?
|
||||
|
||||
¿Cómo se comportaron las ventas frente al mes anterior?
|
||||
|
||||
¿Cuál es nuestro margen promedio?
|
||||
|
||||
Genera un reporte gerencial del mes.
|
||||
|
||||
Genera un Excel con las ventas por vendedor.
|
||||
|
||||
Muéstrame un gráfico de ventas de los últimos 12 meses.
|
||||
|
||||
¿Qué problemas ves en los datos de este mes?
|
||||
```
|
||||
|
||||
Posteriormente:
|
||||
|
||||
```text
|
||||
Analiza la situación comercial de la empresa
|
||||
y dame las principales conclusiones.
|
||||
```
|
||||
|
||||
Las conclusiones deben basarse en datos reales obtenidos de SAP, no en respuestas inventadas por el modelo.
|
||||
|
||||
# Principio de diseño
|
||||
|
||||
La arquitectura debe ser modular.
|
||||
|
||||
Cada nueva capacidad debe incorporarse como una nueva herramienta:
|
||||
|
||||
```text
|
||||
Nueva necesidad
|
||||
|
|
||||
v
|
||||
Nueva Tool
|
||||
|
|
||||
v
|
||||
Consulta / Vista HANA
|
||||
|
|
||||
v
|
||||
Documentación semántica
|
||||
|
|
||||
v
|
||||
Disponible para el agente
|
||||
```
|
||||
|
||||
Esto permite crecer sin rehacer toda la aplicación.
|
||||
|
||||
# Conclusión
|
||||
|
||||
La estrategia recomendada es construir primero un **asistente de consulta sobre SAP Business One**, no un sistema autónomo.
|
||||
|
||||
La combinación:
|
||||
|
||||
```text
|
||||
React
|
||||
+
|
||||
FastAPI
|
||||
+
|
||||
Ollama
|
||||
+
|
||||
Tools Python
|
||||
+
|
||||
SAP HANA
|
||||
+
|
||||
Service Layer
|
||||
```
|
||||
|
||||
es suficiente para construir una primera versión sólida.
|
||||
|
||||
La pieza más importante no será el modelo de IA, sino la **capa de herramientas y conocimiento empresarial** que conectará el lenguaje natural con los datos reales de SAP.
|
||||
|
||||
El modelo puede cambiarse posteriormente. Las herramientas, vistas, reglas de negocio y capa semántica serán el verdadero activo del proyecto.
|
||||
Reference in new issue
Block a user