@kwirthmagnify/kwirth-docs-pinocchio 0.2.31 → 0.2.34
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/admin/01-setup.md +98 -98
- package/admin/02-ai-config.md +125 -125
- package/admin/03-tools.md +132 -131
- package/admin/05-rbac.md +89 -89
- package/admin/06-limits.md +113 -113
- package/index.md +42 -42
- package/package.json +1 -1
- package/user/00-how-it-works.md +88 -88
- package/user/02-ui-tour.md +96 -96
- package/user/05-findings.md +108 -108
package/admin/01-setup.md
CHANGED
|
@@ -1,98 +1,98 @@
|
|
|
1
|
-
# Instalación
|
|
2
|
-
|
|
3
|
-
Pinocchio es un plugin de tipo **canal**. Se instala como cualquier otro plugin de
|
|
4
|
-
dependencia dura y una condición previa que conviene resolver antes de que los usuarios abran el canal.
|
|
5
|
-
|
|
6
|
-
## Requisitos
|
|
7
|
-
|
|
8
|
-
| Requisito | Detalle |
|
|
9
|
-
|-----------|---------|
|
|
10
|
-
| Provider `business` | **Obligatorio.** El manifiesto declara `requiresExtension: ["provider:business:0.1.6"]`.
|
|
11
|
-
| Providers `events` y `metrics` | Los aporta el core. No hay nada que instalar. |
|
|
12
|
-
| Almacenamiento del canal | El canal declara `storage: true`:
|
|
13
|
-
| Un provider de IA y un LLM | **No es un requisito de instalación, pero sí de uso.** Sin ellos el canal arranca y no sirve para nada. Ver [Providers y modelos de IA](02-ai-config.md). |
|
|
14
|
-
| Tipo de clúster | El canal declara `sources: [KUBERNETES]`. No funciona sobre orígenes que no sean Kubernetes. |
|
|
15
|
-
|
|
16
|
-
**Reinicio:** el manifiesto declara `requiresRestart: false`. Instalarlo o actualizarlo no obliga a reiniciar
|
|
17
|
-
el backend de
|
|
18
|
-
|
|
19
|
-
## Instalar en producción
|
|
20
|
-
|
|
21
|
-
Desde la UI de administración de
|
|
22
|
-
desde la URL del tarball publicado:
|
|
23
|
-
|
|
24
|
-
```
|
|
25
|
-
https://registry.npmjs.org/@kwirthmagnify/kwirth-plugin-pinocchio/-/kwirth-plugin-pinocchio-<version>.tgz
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
Instala **antes** el provider `business`; si no, la instalación del plugin se rechaza por dependencia no
|
|
29
|
-
satisfecha.
|
|
30
|
-
|
|
31
|
-
## Instalar en desarrollo
|
|
32
|
-
|
|
33
|
-
En un entorno de desarrollo, el backend carga los plugins desde disco leyendo `back/kwirth-dev.json`:
|
|
34
|
-
|
|
35
|
-
```json
|
|
36
|
-
{
|
|
37
|
-
"plugins": {
|
|
38
|
-
"pinocchio": "../plugins/pinocchio/dist"
|
|
39
|
-
},
|
|
40
|
-
"providers": {
|
|
41
|
-
"business": "../providers/business/dist"
|
|
42
|
-
},
|
|
43
|
-
"docs": {
|
|
44
|
-
"pinocchio": "../plugins/pinocchio/docs/pinocchio.tgz"
|
|
45
|
-
}
|
|
46
|
-
}
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
La entrada de `docs` es la que hace que **esta guía** quede accesible desde la propia UI de
|
|
50
|
-
|
|
51
|
-
## Construir desde fuente
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
cd plugins/pinocchio
|
|
55
|
-
npm install
|
|
56
|
-
npm run build # front.js + back.js + docs/pinocchio.tgz + dist/package.json
|
|
57
|
-
npm run watch # reconstruye todo en cada cambio, la guía incluida
|
|
58
|
-
npm run docs # sólo reempaqueta la guía
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
`build` y `watch` cubren **las tres piezas**: el bundle de front, el de back y el tarball de la guía. No hace
|
|
62
|
-
falta acordarse de empaquetar la documentación por separado.
|
|
63
|
-
|
|
64
|
-
Con `watch` en marcha:
|
|
65
|
-
|
|
66
|
-
- un cambio en `src/front/` lo recoge el navegador solo (el front sondea `front.js` cada 2 s);
|
|
67
|
-
- un cambio en `src/back/` **requiere reiniciar el core**, que cachea el módulo de back;
|
|
68
|
-
- un cambio en `docs/guide/` reconstruye el tarball al vuelo, pero el core lo instala al arrancar, así que se
|
|
69
|
-
ve tras reiniciarlo.
|
|
70
|
-
|
|
71
|
-
## Qué hace el canal al arrancar
|
|
72
|
-
|
|
73
|
-
Cada vez que un usuario abre el canal, la instancia del backend:
|
|
74
|
-
|
|
75
|
-
1. Se suscribe a los providers `metrics`, `business` (espacios `customers.status`, `branches.status`,
|
|
76
|
-
`launch.immediate`) y `events` (los 11 kinds que vigila).
|
|
77
|
-
2. Lee los **providers de IA** del almacén común (`kwirth-ai-providers`) y construye los modelos.
|
|
78
|
-
3. Lee su propia configuración (`pinocchio-config`) del almacén del canal.
|
|
79
|
-
4. Lee los **LLMs** del almacén común (`kwirth-ai-llms`); si hay alguno, sustituye a los que tuviera guardados.
|
|
80
|
-
|
|
81
|
-
> ⚠️ **Los puntos 2 y 4 sólo ocurren al arrancar el canal.** Si un administrador crea un provider desde los
|
|
82
|
-
> menús *AI Providers* del core con el canal ya abierto, ese canal no lo verá hasta que se cierre y se vuelva
|
|
83
|
-
> a abrir. Ver [Límites conocidos](06-limits.md).
|
|
84
|
-
|
|
85
|
-
## Comportamiento del canal
|
|
86
|
-
|
|
87
|
-
Lo que el canal declara al core, y lo que significa para el usuario:
|
|
88
|
-
|
|
89
|
-
| Propiedad | Valor | Efecto |
|
|
90
|
-
|-----------|-------|--------|
|
|
91
|
-
| `routable` | `false` | No se puede dirigir a un recurso concreto: siempre es de clúster. |
|
|
92
|
-
| `pauseable` | `true` | Se puede pausar y continuar. |
|
|
93
|
-
| `modifiable` | `false` | No se puede reconfigurar la instancia en caliente. |
|
|
94
|
-
| `reconnectable` | `true` | Sobrevive a una reconexión del websocket. |
|
|
95
|
-
| `resourced` | `false` | No selecciona namespaces ni pods al arrancar. |
|
|
96
|
-
| `cluster` | `true` | Es un canal de ámbito de clúster. |
|
|
97
|
-
|
|
98
|
-
No tiene diálogo de *Setup*: no hay nada que elegir antes de arrancarlo.
|
|
1
|
+
# Instalación
|
|
2
|
+
|
|
3
|
+
Pinocchio es un plugin de tipo **canal**. Se instala como cualquier otro plugin de Kwirth, pero tiene una
|
|
4
|
+
dependencia dura y una condición previa que conviene resolver antes de que los usuarios abran el canal.
|
|
5
|
+
|
|
6
|
+
## Requisitos
|
|
7
|
+
|
|
8
|
+
| Requisito | Detalle |
|
|
9
|
+
|-----------|---------|
|
|
10
|
+
| Provider `business` | **Obligatorio.** El manifiesto declara `requiresExtension: ["provider:business:0.1.6"]`. Kwirth no deja instalar el plugin sin él. |
|
|
11
|
+
| Providers `events` y `metrics` | Los aporta el core. No hay nada que instalar. |
|
|
12
|
+
| Almacenamiento del canal | El canal declara `storage: true`: Kwirth le da un almacén donde guarda la clave `pinocchio-config`. |
|
|
13
|
+
| Un provider de IA y un LLM | **No es un requisito de instalación, pero sí de uso.** Sin ellos el canal arranca y no sirve para nada. Ver [Providers y modelos de IA](02-ai-config.md). |
|
|
14
|
+
| Tipo de clúster | El canal declara `sources: [KUBERNETES]`. No funciona sobre orígenes que no sean Kubernetes. |
|
|
15
|
+
|
|
16
|
+
**Reinicio:** el manifiesto declara `requiresRestart: false`. Instalarlo o actualizarlo no obliga a reiniciar
|
|
17
|
+
el backend de Kwirth.
|
|
18
|
+
|
|
19
|
+
## Instalar en producción
|
|
20
|
+
|
|
21
|
+
Desde la UI de administración de Kwirth, en el gestor de plugins: búscalo en el marketplace, o instálalo
|
|
22
|
+
desde la URL del tarball publicado:
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
https://registry.npmjs.org/@kwirthmagnify/kwirth-plugin-pinocchio/-/kwirth-plugin-pinocchio-<version>.tgz
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
Instala **antes** el provider `business`; si no, la instalación del plugin se rechaza por dependencia no
|
|
29
|
+
satisfecha.
|
|
30
|
+
|
|
31
|
+
## Instalar en desarrollo
|
|
32
|
+
|
|
33
|
+
En un entorno de desarrollo, el backend carga los plugins desde disco leyendo `back/kwirth-dev.json`:
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"plugins": {
|
|
38
|
+
"pinocchio": "../plugins/pinocchio/dist"
|
|
39
|
+
},
|
|
40
|
+
"providers": {
|
|
41
|
+
"business": "../providers/business/dist"
|
|
42
|
+
},
|
|
43
|
+
"docs": {
|
|
44
|
+
"pinocchio": "../plugins/pinocchio/docs/pinocchio.tgz"
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
La entrada de `docs` es la que hace que **esta guía** quede accesible desde la propia UI de Kwirth.
|
|
50
|
+
|
|
51
|
+
## Construir desde fuente
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
cd plugins/pinocchio
|
|
55
|
+
npm install
|
|
56
|
+
npm run build # front.js + back.js + docs/pinocchio.tgz + dist/package.json
|
|
57
|
+
npm run watch # reconstruye todo en cada cambio, la guía incluida
|
|
58
|
+
npm run docs # sólo reempaqueta la guía
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`build` y `watch` cubren **las tres piezas**: el bundle de front, el de back y el tarball de la guía. No hace
|
|
62
|
+
falta acordarse de empaquetar la documentación por separado.
|
|
63
|
+
|
|
64
|
+
Con `watch` en marcha:
|
|
65
|
+
|
|
66
|
+
- un cambio en `src/front/` lo recoge el navegador solo (el front sondea `front.js` cada 2 s);
|
|
67
|
+
- un cambio en `src/back/` **requiere reiniciar el core**, que cachea el módulo de back;
|
|
68
|
+
- un cambio en `docs/guide/` reconstruye el tarball al vuelo, pero el core lo instala al arrancar, así que se
|
|
69
|
+
ve tras reiniciarlo.
|
|
70
|
+
|
|
71
|
+
## Qué hace el canal al arrancar
|
|
72
|
+
|
|
73
|
+
Cada vez que un usuario abre el canal, la instancia del backend:
|
|
74
|
+
|
|
75
|
+
1. Se suscribe a los providers `metrics`, `business` (espacios `customers.status`, `branches.status`,
|
|
76
|
+
`launch.immediate`) y `events` (los 11 kinds que vigila).
|
|
77
|
+
2. Lee los **providers de IA** del almacén común (`kwirth-ai-providers`) y construye los modelos.
|
|
78
|
+
3. Lee su propia configuración (`pinocchio-config`) del almacén del canal.
|
|
79
|
+
4. Lee los **LLMs** del almacén común (`kwirth-ai-llms`); si hay alguno, sustituye a los que tuviera guardados.
|
|
80
|
+
|
|
81
|
+
> ⚠️ **Los puntos 2 y 4 sólo ocurren al arrancar el canal.** Si un administrador crea un provider desde los
|
|
82
|
+
> menús *AI Providers* del core con el canal ya abierto, ese canal no lo verá hasta que se cierre y se vuelva
|
|
83
|
+
> a abrir. Ver [Límites conocidos](06-limits.md).
|
|
84
|
+
|
|
85
|
+
## Comportamiento del canal
|
|
86
|
+
|
|
87
|
+
Lo que el canal declara al core, y lo que significa para el usuario:
|
|
88
|
+
|
|
89
|
+
| Propiedad | Valor | Efecto |
|
|
90
|
+
|-----------|-------|--------|
|
|
91
|
+
| `routable` | `false` | No se puede dirigir a un recurso concreto: siempre es de clúster. |
|
|
92
|
+
| `pauseable` | `true` | Se puede pausar y continuar. |
|
|
93
|
+
| `modifiable` | `false` | No se puede reconfigurar la instancia en caliente. |
|
|
94
|
+
| `reconnectable` | `true` | Sobrevive a una reconexión del websocket. |
|
|
95
|
+
| `resourced` | `false` | No selecciona namespaces ni pods al arrancar. |
|
|
96
|
+
| `cluster` | `true` | Es un canal de ámbito de clúster. |
|
|
97
|
+
|
|
98
|
+
No tiene diálogo de *Setup*: no hay nada que elegir antes de arrancarlo.
|
package/admin/02-ai-config.md
CHANGED
|
@@ -1,125 +1,125 @@
|
|
|
1
|
-
# Providers y modelos de IA
|
|
2
|
-
|
|
3
|
-
Esta es la configuración que hay que resolver **antes** de que Pinocchio sirva para algo. Y lo primero que
|
|
4
|
-
hay que entender es que **no es configuración de Pinocchio**.
|
|
5
|
-
|
|
6
|
-
## La configuración de IA es de
|
|
7
|
-
|
|
8
|
-
Pinocchio no guarda sus propios providers ni sus propios modelos. Los lee del **almacén común de
|
|
9
|
-
compartido con todos los demás plugins que usan IA:
|
|
10
|
-
|
|
11
|
-
| Qué | Clave | Dónde |
|
|
12
|
-
|-----|-------|-------|
|
|
13
|
-
| Providers (con las API keys) | `kwirth-ai-providers` | **Secret** de Kubernetes |
|
|
14
|
-
| LLMs | `kwirth-ai-llms` | **ConfigMap** de Kubernetes |
|
|
15
|
-
|
|
16
|
-
Las consecuencias prácticas son tres:
|
|
17
|
-
|
|
18
|
-
1. Si ya configuraste un provider para otro plugin, **Pinocchio lo ve**. No hay que repetir nada.
|
|
19
|
-
2. Si lo configuras desde Pinocchio, **lo verán los demás**. Los diálogos del grupo *AI* del menú Config
|
|
20
|
-
(*AI providers* / *AI models*) son literalmente los mismos componentes comunes
|
|
21
|
-
(`AiConfigProvider` / `AiConfigLlm`) que usa el core en sus menús *AI Providers* / *AI Models*.
|
|
22
|
-
3. Las claves viven en un **Secret**, no en un ConfigMap. Quien tenga permiso de lectura sobre los Secrets del
|
|
23
|
-
namespace de
|
|
24
|
-
|
|
25
|
-
## Provider
|
|
26
|
-
|
|
27
|
-
Un *provider* es una cuenta contra un proveedor de IA: el adaptador y la clave.
|
|
28
|
-
|
|
29
|
-
| Campo | Qué es |
|
|
30
|
-
|-------|--------|
|
|
31
|
-
| `Name` | Identificador libre de **esta** instancia de provider (`openai-prod`, `huawei-maas`). Es lo que referencian los LLMs. |
|
|
32
|
-
| `Type` | El adaptador de SDK. Lista cerrada: `google`, `openai`, `openrouter`, `mistral`, `groq`, `deepseek`, `anthropic`, `openai-compat`. |
|
|
33
|
-
| `API Key / Token` | La credencial. Campo de contraseña con botón de ojo para revelarla. |
|
|
34
|
-
| `Base URL` | **Sólo para `openai-compat`.** La URL base de la API compatible con OpenAI (Huawei MaaS, vLLM, LM Studio…). Debe apuntar a la raíz; el adaptador añade `/v1` si falta. |
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
Al elegir un `Type`, si el nombre está vacío se rellena solo con el tipo. **Déjalo así salvo que tengas una
|
|
39
|
-
razón** — ver la advertencia del final de la página.
|
|
40
|
-
|
|
41
|
-
**Load models** consulta al proveedor el catálogo de modelos disponibles y lo cachea en el provider. La
|
|
42
|
-
llamada la hace el **core** de
|
|
43
|
-
quien tiene los adaptadores de cada SDK. Si el botón no aparece o falla, revisa que la clave sea válida.
|
|
44
|
-
|
|
45
|
-
Sin modelos cargados, el provider aparece **deshabilitado** en el desplegable del diálogo de LLM.
|
|
46
|
-
|
|
47
|
-
> ⚠️ El botón **Export** de este diálogo descarga `kwirth-providers.json` **con las API keys en claro**.
|
|
48
|
-
> Trátalo como un secreto: no lo subas a un repositorio ni lo mandes por correo.
|
|
49
|
-
|
|
50
|
-
## LLM
|
|
51
|
-
|
|
52
|
-
Un *LLM* es un modelo concreto de un provider concreto, con sus parámetros. Es lo que referencian los
|
|
53
|
-
triggers, por su `LLM ID`.
|
|
54
|
-
|
|
55
|
-
| Campo | Qué es |
|
|
56
|
-
|-------|--------|
|
|
57
|
-
| `LLM ID` | El identificador que usarán los triggers. **Elígelo con cuidado**: es lo que viaja en un export de triggers. |
|
|
58
|
-
| `Provider` | Uno de los providers configurados. Sólo se pueden elegir los que tienen modelos cargados. |
|
|
59
|
-
| `Model` | Desplegable con los modelos cargados del provider; si el provider no tiene catálogo, se convierte en una caja de texto libre. |
|
|
60
|
-
| `Model temperature` | Temperatura. ⚠️ Pinocchio la **recorta al rango 0–1** antes de llamar al modelo. |
|
|
61
|
-
| `Input / Output cost / M tokens` | Coste informativo por millón de tokens. No lo usa el motor: es para que puedas calcular la factura. |
|
|
62
|
-
| `Use provider API Key` | Si está marcado, usa la clave del provider. Si no, puedes darle una clave específica a este LLM. |
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
Para análisis de seguridad, **temperatura baja** (0 – 0.2). Lo que quieres es un auditor consistente, no uno
|
|
67
|
-
creativo.
|
|
68
|
-
|
|
69
|
-
## Salida estructurada: no todos los modelos valen
|
|
70
|
-
|
|
71
|
-
Los triggers de tipo `artifact` exigen al modelo una respuesta que cumpla un esquema JSON estricto. Un modelo
|
|
72
|
-
pequeño o antiguo que no soporte *structured output* fallará sistemáticamente, y lo verás como un análisis con
|
|
73
|
-
dos findings `critical` y el error del proveedor.
|
|
74
|
-
|
|
75
|
-
Pinocchio añade opciones específicas por proveedor para que esto funcione:
|
|
76
|
-
|
|
77
|
-
| Proveedor | Opciones que envía |
|
|
78
|
-
|-----------|--------------------|
|
|
79
|
-
| `google` | `{ google: { structuredOutputs: true } }` |
|
|
80
|
-
| `groq` | `{ groq: { structuredOutputs: true } }` |
|
|
81
|
-
| `mistral` | `{ mistral: { strictJsonSchema: true, structuredOutputs: true } }` |
|
|
82
|
-
| cualquier otro | `{ openai: {} }` |
|
|
83
|
-
|
|
84
|
-
> ⚠️ **Gotcha importante.** Esa tabla se elige por el **`Name`** del provider, no por su `Type`. El modelo
|
|
85
|
-
> sí se construye correctamente por el tipo, pero las opciones de salida estructurada no.
|
|
86
|
-
>
|
|
87
|
-
> Es decir: un provider de tipo `google` llamado `google` funciona; el **mismo** provider llamado
|
|
88
|
-
> `gemini-prod` construye el modelo bien pero **pierde** el `structuredOutputs: true`, y los triggers
|
|
89
|
-
> `artifact` pueden empezar a fallar sin motivo aparente.
|
|
90
|
-
>
|
|
91
|
-
> **Recomendación: deja el `Name` del provider igual que su `Type`** mientras no tengas que crear dos cuentas
|
|
92
|
-
> del mismo proveedor. Si necesitas varias, usa una con el nombre canónico para Pinocchio. Está recogido en
|
|
93
|
-
> [Límites conocidos](06-limits.md).
|
|
94
|
-
|
|
95
|
-
## El orden importa
|
|
96
|
-
|
|
97
|
-
El menú Config va habilitando entradas conforme cumples los requisitos:
|
|
98
|
-
|
|
99
|
-
```
|
|
100
|
-
AI ▸ AI providers (siempre)
|
|
101
|
-
|
|
|
102
|
-
v con >= 1 provider
|
|
103
|
-
AI ▸ AI models
|
|
104
|
-
|
|
|
105
|
-
v con >= 1 LLM
|
|
106
|
-
Trigger
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
Si un usuario te dice que "Trigger está en gris", no es un fallo del plugin: falta el LLM.
|
|
110
|
-
|
|
111
|
-
## Cuándo lee el canal esta configuración
|
|
112
|
-
|
|
113
|
-
**Sólo al arrancar la instancia del canal.** Si creas un provider o un LLM desde los menús *AI Providers* /
|
|
114
|
-
*AI Models* del core mientras un usuario tiene el canal abierto, ese usuario no lo verá hasta cerrar y
|
|
115
|
-
reabrir el canal.
|
|
116
|
-
|
|
117
|
-
En cambio, si lo creas **desde el propio menú Config de Pinocchio**, el canal sí se entera al momento: el
|
|
118
|
-
plugin manda un `PROVIDERSSET`/`CONFIGSET` que reescribe el almacén y recarga los modelos.
|
|
119
|
-
|
|
120
|
-
## Multi-clúster
|
|
121
|
-
|
|
122
|
-
La configuración de IA **no viaja entre clústeres**. Los menús del core escriben en el backend **local**,
|
|
123
|
-
pero un canal abierto contra otro
|
|
124
|
-
que configurar providers y LLMs en cada clúster, y con los **mismos ids de LLM** si quieres poder mover
|
|
125
|
-
triggers entre ellos. Ver [Límites conocidos](06-limits.md).
|
|
1
|
+
# Providers y modelos de IA
|
|
2
|
+
|
|
3
|
+
Esta es la configuración que hay que resolver **antes** de que Pinocchio sirva para algo. Y lo primero que
|
|
4
|
+
hay que entender es que **no es configuración de Pinocchio**.
|
|
5
|
+
|
|
6
|
+
## La configuración de IA es de Kwirth, no del plugin
|
|
7
|
+
|
|
8
|
+
Pinocchio no guarda sus propios providers ni sus propios modelos. Los lee del **almacén común de Kwirth**,
|
|
9
|
+
compartido con todos los demás plugins que usan IA:
|
|
10
|
+
|
|
11
|
+
| Qué | Clave | Dónde |
|
|
12
|
+
|-----|-------|-------|
|
|
13
|
+
| Providers (con las API keys) | `kwirth-ai-providers` | **Secret** de Kubernetes |
|
|
14
|
+
| LLMs | `kwirth-ai-llms` | **ConfigMap** de Kubernetes |
|
|
15
|
+
|
|
16
|
+
Las consecuencias prácticas son tres:
|
|
17
|
+
|
|
18
|
+
1. Si ya configuraste un provider para otro plugin, **Pinocchio lo ve**. No hay que repetir nada.
|
|
19
|
+
2. Si lo configuras desde Pinocchio, **lo verán los demás**. Los diálogos del grupo *AI* del menú Config
|
|
20
|
+
(*AI providers* / *AI models*) son literalmente los mismos componentes comunes
|
|
21
|
+
(`AiConfigProvider` / `AiConfigLlm`) que usa el core en sus menús *AI Providers* / *AI Models*.
|
|
22
|
+
3. Las claves viven en un **Secret**, no en un ConfigMap. Quien tenga permiso de lectura sobre los Secrets del
|
|
23
|
+
namespace de Kwirth puede leerlas.
|
|
24
|
+
|
|
25
|
+
## Provider
|
|
26
|
+
|
|
27
|
+
Un *provider* es una cuenta contra un proveedor de IA: el adaptador y la clave.
|
|
28
|
+
|
|
29
|
+
| Campo | Qué es |
|
|
30
|
+
|-------|--------|
|
|
31
|
+
| `Name` | Identificador libre de **esta** instancia de provider (`openai-prod`, `huawei-maas`). Es lo que referencian los LLMs. |
|
|
32
|
+
| `Type` | El adaptador de SDK. Lista cerrada: `google`, `openai`, `openrouter`, `mistral`, `groq`, `deepseek`, `anthropic`, `openai-compat`. |
|
|
33
|
+
| `API Key / Token` | La credencial. Campo de contraseña con botón de ojo para revelarla. |
|
|
34
|
+
| `Base URL` | **Sólo para `openai-compat`.** La URL base de la API compatible con OpenAI (Huawei MaaS, vLLM, LM Studio…). Debe apuntar a la raíz; el adaptador añade `/v1` si falta. |
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
Al elegir un `Type`, si el nombre está vacío se rellena solo con el tipo. **Déjalo así salvo que tengas una
|
|
39
|
+
razón** — ver la advertencia del final de la página.
|
|
40
|
+
|
|
41
|
+
**Load models** consulta al proveedor el catálogo de modelos disponibles y lo cachea en el provider. La
|
|
42
|
+
llamada la hace el **core** de Kwirth (`POST /core/aiconfig/loadmodels`), no el plugin, porque es el core
|
|
43
|
+
quien tiene los adaptadores de cada SDK. Si el botón no aparece o falla, revisa que la clave sea válida.
|
|
44
|
+
|
|
45
|
+
Sin modelos cargados, el provider aparece **deshabilitado** en el desplegable del diálogo de LLM.
|
|
46
|
+
|
|
47
|
+
> ⚠️ El botón **Export** de este diálogo descarga `kwirth-providers.json` **con las API keys en claro**.
|
|
48
|
+
> Trátalo como un secreto: no lo subas a un repositorio ni lo mandes por correo.
|
|
49
|
+
|
|
50
|
+
## LLM
|
|
51
|
+
|
|
52
|
+
Un *LLM* es un modelo concreto de un provider concreto, con sus parámetros. Es lo que referencian los
|
|
53
|
+
triggers, por su `LLM ID`.
|
|
54
|
+
|
|
55
|
+
| Campo | Qué es |
|
|
56
|
+
|-------|--------|
|
|
57
|
+
| `LLM ID` | El identificador que usarán los triggers. **Elígelo con cuidado**: es lo que viaja en un export de triggers. |
|
|
58
|
+
| `Provider` | Uno de los providers configurados. Sólo se pueden elegir los que tienen modelos cargados. |
|
|
59
|
+
| `Model` | Desplegable con los modelos cargados del provider; si el provider no tiene catálogo, se convierte en una caja de texto libre. |
|
|
60
|
+
| `Model temperature` | Temperatura. ⚠️ Pinocchio la **recorta al rango 0–1** antes de llamar al modelo. |
|
|
61
|
+
| `Input / Output cost / M tokens` | Coste informativo por millón de tokens. No lo usa el motor: es para que puedas calcular la factura. |
|
|
62
|
+
| `Use provider API Key` | Si está marcado, usa la clave del provider. Si no, puedes darle una clave específica a este LLM. |
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
Para análisis de seguridad, **temperatura baja** (0 – 0.2). Lo que quieres es un auditor consistente, no uno
|
|
67
|
+
creativo.
|
|
68
|
+
|
|
69
|
+
## Salida estructurada: no todos los modelos valen
|
|
70
|
+
|
|
71
|
+
Los triggers de tipo `artifact` exigen al modelo una respuesta que cumpla un esquema JSON estricto. Un modelo
|
|
72
|
+
pequeño o antiguo que no soporte *structured output* fallará sistemáticamente, y lo verás como un análisis con
|
|
73
|
+
dos findings `critical` y el error del proveedor.
|
|
74
|
+
|
|
75
|
+
Pinocchio añade opciones específicas por proveedor para que esto funcione:
|
|
76
|
+
|
|
77
|
+
| Proveedor | Opciones que envía |
|
|
78
|
+
|-----------|--------------------|
|
|
79
|
+
| `google` | `{ google: { structuredOutputs: true } }` |
|
|
80
|
+
| `groq` | `{ groq: { structuredOutputs: true } }` |
|
|
81
|
+
| `mistral` | `{ mistral: { strictJsonSchema: true, structuredOutputs: true } }` |
|
|
82
|
+
| cualquier otro | `{ openai: {} }` |
|
|
83
|
+
|
|
84
|
+
> ⚠️ **Gotcha importante.** Esa tabla se elige por el **`Name`** del provider, no por su `Type`. El modelo
|
|
85
|
+
> sí se construye correctamente por el tipo, pero las opciones de salida estructurada no.
|
|
86
|
+
>
|
|
87
|
+
> Es decir: un provider de tipo `google` llamado `google` funciona; el **mismo** provider llamado
|
|
88
|
+
> `gemini-prod` construye el modelo bien pero **pierde** el `structuredOutputs: true`, y los triggers
|
|
89
|
+
> `artifact` pueden empezar a fallar sin motivo aparente.
|
|
90
|
+
>
|
|
91
|
+
> **Recomendación: deja el `Name` del provider igual que su `Type`** mientras no tengas que crear dos cuentas
|
|
92
|
+
> del mismo proveedor. Si necesitas varias, usa una con el nombre canónico para Pinocchio. Está recogido en
|
|
93
|
+
> [Límites conocidos](06-limits.md).
|
|
94
|
+
|
|
95
|
+
## El orden importa
|
|
96
|
+
|
|
97
|
+
El menú Config va habilitando entradas conforme cumples los requisitos:
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
AI ▸ AI providers (siempre)
|
|
101
|
+
|
|
|
102
|
+
v con >= 1 provider
|
|
103
|
+
AI ▸ AI models
|
|
104
|
+
|
|
|
105
|
+
v con >= 1 LLM
|
|
106
|
+
Trigger
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Si un usuario te dice que "Trigger está en gris", no es un fallo del plugin: falta el LLM.
|
|
110
|
+
|
|
111
|
+
## Cuándo lee el canal esta configuración
|
|
112
|
+
|
|
113
|
+
**Sólo al arrancar la instancia del canal.** Si creas un provider o un LLM desde los menús *AI Providers* /
|
|
114
|
+
*AI Models* del core mientras un usuario tiene el canal abierto, ese usuario no lo verá hasta cerrar y
|
|
115
|
+
reabrir el canal.
|
|
116
|
+
|
|
117
|
+
En cambio, si lo creas **desde el propio menú Config de Pinocchio**, el canal sí se entera al momento: el
|
|
118
|
+
plugin manda un `PROVIDERSSET`/`CONFIGSET` que reescribe el almacén y recarga los modelos.
|
|
119
|
+
|
|
120
|
+
## Multi-clúster
|
|
121
|
+
|
|
122
|
+
La configuración de IA **no viaja entre clústeres**. Los menús del core escriben en el backend **local**,
|
|
123
|
+
pero un canal abierto contra otro Kwirth lee el almacén de **ese** clúster. Si operas una federación, tienes
|
|
124
|
+
que configurar providers y LLMs en cada clúster, y con los **mismos ids de LLM** si quieres poder mover
|
|
125
|
+
triggers entre ellos. Ver [Límites conocidos](06-limits.md).
|