Configuración de la marca de la empresa#

La marca permite adaptar Sherpa AI Server al estilo de la empresa y elegir la navegación para sus Usuarios.

Configuración de branding.json en Sherpa AI Server#

El archivo branding.json permite cambiar la apariencia y la navegación sin modificar el código fuente.

Propósito#

Este artículo está dirigido al administrador que cambia la apariencia de una instalación de Sherpa AI Server. La configuración se realiza mediante un archivo del servidor. Los comandos Docker permiten que el servidor web cargue ese archivo en lugar del estándar. La interfaz no tiene un editor de branding.json.

El archivo branding.json cambia la apariencia y parte del comportamiento sin volver a compilar la interfaz web:

  • nombre y logotipos;
  • colores principales, radio de las esquinas y fuente;
  • fondo de los mensajes del usuario y del Asistente;
  • idioma predeterminado e idiomas disponibles;
  • visualización del botón de inicio de sesión con OpenID;
  • visualización del selector de Chats compartidos y personales en el panel lateral;
  • enlaces adicionales en el menú lateral;
  • un botón de información en la página de inicio de sesión.

La configuración se aplica en el navegador cuando se carga la aplicación.

Dónde se encuentra el archivo#

La ubicación del archivo permite identificar la configuración adecuada para el desarrollo o el sistema instalado.

En el código fuente#

La ruta en el código fuente permite preparar la marca durante el desarrollo.

Archivo principal:

frontend/src/assets/branding/branding.json

Se incluye en la compilación del frontend y se usa como el conjunto de configuración predeterminado para la distribución.

En la distribución del cliente#

El archivo de la distribución del cliente permite cambiar la marca de la aplicación instalada.

Al preparar el paquete del cliente, el archivo se copia aquí:

frontend/config/branding.json

Para utilizar la configuración del cliente, se conecta frontend/config/branding.json al contenedor aiserver-nginx mediante esta entrada en docker-compose.yml:

services:
  aiserver-nginx:
    volumes:
      - ./frontend/config/branding.json:/opt/SherpaAIServer/frontend/dist/assets/branding/branding.json:ro

En el docker-compose.yml distribuido, esta línea puede estar comentada. Después de habilitar el montaje por primera vez, vuelva a crear el contenedor:

docker compose up -d --force-recreate aiserver-nginx

Después de modificar un archivo ya conectado, es necesario recargar la página y comprobar que el servidor entregue la nueva configuración. Si sigue entregando el archivo anterior, se vuelve a crear aiserver-nginx con el mismo comando.

Cómo se carga la configuración#

El orden de carga permite comprobar qué configuración recibe el navegador después de modificar el archivo.

Cuando el frontend inicia, solicita:

/assets/branding/branding.json

La configuración se carga antes de abrir la interfaz. El idioma, los logotipos, los colores y la fuente seleccionados se aplican desde el inicio.

Reglas de carga:

  1. Los valores integrados de Sherpa AI Server se usan como base.
  2. Los campos de branding.json reemplazan los valores integrados correspondientes.
  3. Si el archivo no está disponible o contiene JSON inválido, la aplicación sigue funcionando con los valores integrados.
  4. Los campos de nivel superior que falten no necesitan especificarse: para ellos se conservan los valores integrados.
  5. Los objetos anidados y los elementos de arreglos deben definirse por completo. Excepción: los campos de primer nivel de chat_model_picker_text se completan con valores integrados.

El campo _comments dentro del branding.json estándar contiene descripciones de referencia. Es un campo auxiliar normal de JSON. La interfaz no lo usa.

La configuración personal de apariencia guardada en el navegador tiene prioridad sobre los colores, las fuentes, los logotipos y los fondos del archivo del servidor. Para comprobar la configuración del servidor sin esos cambios, es necesario abrir Sherpa AI Server en otro perfil del navegador.

Inicio rápido#

El inicio rápido permite aplicar su propio nombre y estilo a la aplicación instalada.

Para aplicar la configuración, es necesario realizar los siguientes pasos:

  1. Guarde una copia de frontend/config/branding.json y después prepare o edite el archivo de trabajo.

  2. Asegúrese de que el bind mount esté habilitado en docker-compose.yml.

  3. Verifique la sintaxis del JSON:

    jq empty frontend/config/branding.json
    
  4. Al conectar el archivo por primera vez, vuelva a crear aiserver-nginx:

    docker compose up -d --force-recreate aiserver-nginx
    
  5. Verifique qué archivo está sirviendo el servidor:

    Sustituya ai.example.org por la dirección de su instalación.

    curl -fsS https://ai.example.org/assets/branding/branding.json | jq .
    
  6. Recargue la página de Sherpa AI Server. Si el navegador muestra recursos antiguos, realice una recarga forzada.

Ejemplo completo#

El ejemplo configura el nombre "Корпоративный AI", logotipos para los temas claro y oscuro, botones azules y la fuente Inter. Antes de aplicarlo, es necesario preparar los logotipos y sustituir la dirección de soporte por la de su organización. Los parámetros se añaden al archivo de trabajo conservando los demás ajustes utilizados.

{
  "app_name": "Корпоративный AI",
  "logo_url": "assets/branding/logo-light-v1.svg",
  "logo_url_light": "assets/branding/logo-light-v1.svg",
  "logo_url_dark": "assets/branding/logo-dark-v1.svg",
  "favicon_url": "favicon.ico",
  "disable_openid": false,
  "hide_chat_scope_switch": false,
  "hide_language_selector": false,
  "hide_unavailable_menu_items": false,
  "auto_expand_sidebar_sections": false,
  "default_language": "ru",
  "available_languages": ["ru", "en"],
  "additional_menu_items": [
    {
      "button_name": {
        "ru": "Поддержка",
        "en": "Support"
      },
      "url": "https://support.example.org",
      "icon": "question-mark-circle-outline"
    },
    {
      "button_name": {
        "ru": "Инструкции",
        "en": "Documentation"
      },
      "url": "/main/documents",
      "icon": "book-open-outline"
    }
  ],
  "additional_login_button": {
    "button_name": {
      "ru": "Как получить доступ?",
      "en": "How do I get access?"
    },
    "message": {
      "ru": "Для получения доступа обратитесь в службу поддержки.",
      "en": "Contact the support team to request access."
    }
  },
  "primary_color": "#2563eb",
  "primary_dark_color": "#1d4ed8",
  "primary_light_color": "#60a5fa",
  "primary_rgb": "37, 99, 235",
  "secondary_color": "#1f2937",
  "border_radius": "8px",
  "font_family": "Inter, sans-serif",
  "font_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap",
  "chat_user_bg": "#eff6ff",
  "chat_assistant_bg": "#ffffff"
}

Descripción de los parámetros#

Esta tabla de referencia describe los principales parámetros del archivo, no campos de un formulario. Complementa los ejemplos de comandos y JSON del artículo.

Parámetro Formato Propósito
app_name cadena Nombre en el menú lateral, texto alt del logotipo y título de la pestaña (<title>).
logo_url cadena URL Logotipo de reserva por compatibilidad. Se usa si no se define un logotipo separado para el tema requerido.
logo_url_light cadena URL Logotipo para el tema claro.
logo_url_dark cadena URL Logotipo para el tema oscuro.
favicon_url cadena URL Icono de la pestaña del navegador. Ruta relativa dentro del frontend o URL absoluta. Por defecto favicon.ico.
disable_openid true o false Cuando es true, oculta el botón "Login with OpenID" en la página de inicio de sesión. El parámetro controla la interfaz y por sí mismo no desactiva OpenID en el backend.
hide_chat_scope_switch true / false Con true, oculta el selector Chats compartidos / Personales en la barra lateral normal y compacta. Por defecto false. El tipo de inicio de sesión sigue determinando la lista.
hide_language_selector true / false Con true, oculta el selector de idioma en la página de inicio de sesión y en la cabecera. Por defecto false.
hide_unavailable_menu_items true / false Con true, oculta los elementos del menú no disponibles según el rol del Usuario. Por defecto false, que los muestra deshabilitados.
auto_expand_sidebar_sections true / false Con false, las secciones Chat, Asistentes y API no se expanden automáticamente al iniciar sesión ni al navegar entre pantallas. Se pueden expandir manualmente. El valor predeterminado es true: las secciones se expanden automáticamente.
default_language ru o en Idioma predeterminado. El valor debe estar presente en available_languages.
available_languages arreglo de ru y/o en Idiomas disponibles para el usuario. Otros valores se descartan.
additional_menu_items arreglo de objetos Elementos permanentes adicionales en el menú lateral antes de la sección Chat.
additional_login_button objeto o null Botón informativo en la página de inicio de sesión. Al hacer clic, abre un diálogo con texto localizado. null oculta el botón.
primary_color #RRGGBB Color principal para botones, enlaces, elementos activos, tablas y controles de formulario.
primary_dark_color #RRGGBB Sombra más oscura del color principal para los estados de hover y pulsación y algunos interruptores.
primary_light_color #RRGGBB Sombra más clara para resaltados y estados secundarios.
primary_rgb cadena R, G, B Componentes RGB de primary_color para fondos translúcidos, sombras y resaltados.
secondary_color color CSS Color secundario. También se usa para las superficies de las tarjetas en el tema oscuro y la pantalla de inicio.
border_radius tamaño CSS Redondeo de elementos, por ejemplo 0px, 6px o 16px.
font_family font-family CSS Familia tipográfica aplicada a la interfaz.
font_url URL de archivo CSS Hoja de estilos desde la que el navegador carga la fuente. Una cadena vacía desactiva la descarga adicional.
chat_user_bg color CSS Fondo de los mensajes del usuario en la pantalla Chat.
chat_assistant_bg color CSS Fondo de las respuestas del Asistente en la pantalla Chat.
home_featured_cards arreglo de objetos Tarjetas principales de Inicio. El formato y los valores de reserva se describen en Tarjetas de Inicio.

Ocultar el selector de tipo de chat#

Para ocultar el selector de chats Compartidos / Personales en la barra lateral, configure lo siguiente en branding.json:

{
  "hide_chat_scope_switch": true
}

Solo cambia la visibilidad del selector. El inicio de sesión de un Usuario sigue abriendo sus chats personales. El de una Cuenta abre los chats compartidos. Para restaurar el selector, establezca false o elimine el parámetro y vuelva a cargar la página.

Configuración de los logotipos#

Los logotipos separados permiten mantener la marca legible en los temas claro y oscuro.

Prioridad de selección del logotipo para cada tema:

logo_url_light или logo_url_dark → logo_url → встроенный логотип

Los logotipos de ambos temas ya están definidos de forma predeterminada. Para cambiarlos, es necesario definir logo_url_light y logo_url_dark. Cambiar solo logo_url no sustituye los logotipos de cada tema.

Se puede usar:

  • una ruta relativa dentro del frontend, por ejemplo assets/branding/logo-light-v1.svg;
  • una ruta absoluta desde la raíz del sitio, por ejemplo /assets/branding/logo-light-v1.svg;
  • una URL absoluta, por ejemplo https://static.example.org/logo-light-v1.svg.

Si el logotipo se almacena junto con la configuración del cliente, móntelo por separado en docker-compose.yml:

services:
  aiserver-nginx:
    volumes:
      - ./frontend/config/branding.json:/opt/SherpaAIServer/frontend/dist/assets/branding/branding.json:ro
      - ./frontend/config/logo-light-v1.svg:/opt/SherpaAIServer/frontend/dist/assets/branding/logo-light-v1.svg:ro
      - ./frontend/config/logo-dark-v1.svg:/opt/SherpaAIServer/frontend/dist/assets/branding/logo-dark-v1.svg:ro

El navegador puede conservar imágenes y fuentes anteriores en la caché. Cuando cambie el contenido del logotipo, use un nombre nuevo, por ejemplo logo-light-v2.svg, y actualice la ruta en branding.json.

Configure favicon_url para el icono de la pestaña del navegador. Si utiliza un archivo propio, asegúrese de que los navegadores puedan acceder a su URL y, si es necesario, móntelo en el contenedor nginx igual que los logotipos. Use un nombre de archivo nuevo al cambiar el icono para evitar la caché.

Configuración de los colores#

Los colores permiten adaptar los botones y otros elementos destacados al estilo de la empresa.

primary_color y primary_rgb describen el mismo color en formatos distintos. No se sincronizan automáticamente.

Ejemplo:

{
  "primary_color": "#2563eb",
  "primary_rgb": "37, 99, 235"
}

Para primary_color, primary_dark_color y primary_light_color, se debe usar el formato HEX completo #RRGGBB. El servicio calcula el contraste del color principal para el texto y los iconos, por lo que no se deben usar HEX abreviado ni valores rgb(...) o rgba(...) para estos tres campos.

Para secondary_color, chat_user_bg y chat_assistant_bg, se permiten colores CSS normales, por ejemplo HEX o rgba(...).

Después de cambiar los colores, compruebe ambos temas, las tablas, los campos de formulario, los botones y la legibilidad de los mensajes en el chat.

Configuración de la fuente#

La configuración de la fuente permite utilizar la tipografía corporativa en la interfaz.

font_url debe apuntar a un archivo CSS con la fuente, y font_family debe apuntar al nombre de familia de ese archivo CSS:

{
  "font_family": "Inter, sans-serif",
  "font_url": "https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap"
}

Para una fuente personalizada, se puede montar el CSS y los archivos de la fuente en el directorio frontend y usar una URL relativa. Asegúrese de que la URL sea accesible desde los navegadores de los usuarios, no solo desde el backend de Sherpa AI Server.

Para no cargar un archivo CSS adicional, deje font_url vacío:

{
  "font_family": "Roboto, 'Helvetica Neue', sans-serif",
  "font_url": ""
}

Idiomas de la interfaz#

La configuración de idiomas permite elegir las traducciones disponibles para los Usuarios y el idioma predeterminado.

Solo se admiten los valores ru y en.

Si available_languages está vacío, tiene un formato no válido o no contiene valores admitidos, Sherpa AI Server habilita ambos idiomas. Si default_language no está presente en la lista de idiomas disponibles, el primer elemento de available_languages pasa a ser el idioma predeterminado.

Ejemplo de una interfaz solo en ruso:

{
  "default_language": "ru",
  "available_languages": ["ru"]
}

El botón del idioma actual sigue visible, pero el menú selector no se abre.

El idioma real se selecciona en este orden:

  1. el parámetro lang o locale en la URL;
  2. el idioma seleccionado previamente en el navegador;
  3. default_language de branding.json.

El valor de la URL o del navegador solo se aplica cuando el idioma está presente en available_languages.

Para ocultar el botón de idioma en la página de inicio de sesión y en la cabecera, configure "hide_language_selector": true. Déjelo en false si los Usuarios deben poder cambiar el idioma.

Visualización de secciones no disponibles#

La visibilidad de los elementos no disponibles permite centrar la navegación en las pantallas a las que el Usuario tiene acceso.

El parámetro hide_unavailable_menu_items cambia la visibilidad del menú izquierdo, no los permisos del Rol. Con true, se ocultan las secciones no disponibles. Con false, permanecen visibles pero inactivas.

Elementos adicionales del menú#

Los elementos adicionales del menú ofrecen enlaces permanentes a soporte y otros recursos útiles junto a la navegación principal.

El parámetro additional_menu_items añade enlaces permanentes al menú lateral. En el ejemplo, "Поддержка" abre el sitio de soporte. Cada elemento utiliza estos parámetros:

{
  "button_name": {
    "ru": "Поддержка",
    "en": "Support"
  },
  "url": "https://support.example.org",
  "icon": "question-mark-circle-outline"
}

Reglas:

  • se requiere al menos una traducción no vacía del nombre;
  • url debe ser una ruta interna con una sola / inicial o una URL con el protocolo http o https;
  • los valores con otros protocolos y las URL no válidas se ignoran;
  • los enlaces internos se abren a través del enrutador de Sherpa AI Server;
  • los enlaces externos se abren en la pestaña actual;
  • los elementos se muestran en el mismo orden que en el arreglo;
  • para un icono estándar, especifique un nombre de Eva Icons, por ejemplo book-open-outline;
  • una cadena que contenga / o termine en .svg se interpreta como la ruta a un icono SVG personalizado.

Si falta una traducción, se usa primero el ruso y luego el inglés.

Botón de información en la página de inicio de sesión#

Un botón informativo en la página de acceso indica al Usuario dónde obtener ayuda antes de iniciar sesión en Sherpa AI Server.

El parámetro additional_login_button añade un botón informativo a la página de inicio de sesión. En el ejemplo, "Forgot your password?" muestra un mensaje para contactar con soporte. No cambia la contraseña ni inicia su recuperación.

{
  "additional_login_button": {
    "button_name": {
      "ru": "Забыли пароль?",
      "en": "Forgot your password?"
    },
    "message": {
      "ru": "Обратитесь в службу поддержки.",
      "en": "Contact the support team."
    }
  }
}

El botón se muestra si hay al menos un nombre y al menos un texto de mensaje completados. El texto se muestra como texto plano, no como HTML. Si falta la traducción del botón, la interfaz utiliza la versión rusa y, después, la inglesa.

Para ocultar el botón informativo, se establece additional_login_button en null:

{
  "additional_login_button": null
}

Tarjetas de Inicio#

Las tarjetas de Inicio permiten colocar las secciones necesarias para los Usuarios en la pantalla inicial.

El parámetro home_featured_cards define las tarjetas de "Get started" en Inicio. El orden coincide con el del arreglo y no se limita a cuatro tarjetas. Para añadir, eliminar o renombrar una tarjeta, es necesario modificar el arreglo en el branding.json del cliente y recargar la página.

El ejemplo define una tarjeta de chat. Agregue este campo a la configuración existente conservando las demás opciones:

{
  "home_featured_cards": [
    {
      "id": "chat",
      "title": { "ru": "Чат", "en": "Chat" },
      "description": { "ru": "Новый диалог", "en": "New conversation" },
      "icon": "message-circle-outline",
      "action": { "type": "route", "url": "/main/new-chat" }
    }
  ]
}

Para cada tarjeta, indique un id único, title y description no vacíos en ru y en, un nombre de icon y una acción action. La acción route abre una ruta interna accesible. La acción assistant con assistant_guid abre un chat nuevo con ese Asistente. Obtenga el GUID de un Asistente existente y accesible.

Un arreglo válido reemplaza por completo el conjunto estándar. Si el campo no existe, es null, contiene un arreglo vacío o tarjetas no válidas, se usan las tarjetas integradas en la aplicación. Un arreglo vacío no oculta todas las tarjetas. Se filtran las secciones no disponibles según los permisos. Una tarjeta con la acción assistant solo aparece con permisos de lectura de Chat y Asistentes. Esta opción no cambia los permisos del rol ni el acceso a los Asistentes.

Los Asistentes fijados se agregan automáticamente después de las tarjetas de home_featured_cards. Este parámetro no controla qué Asistentes están fijados. Si un Asistente ya figura en la configuración, no se muestra una segunda tarjeta.

Si los cambios no aparecen, revise la sintaxis JSON, el archivo cargado y los permisos de la cuenta. Si el GUID de un Asistente no es válido, corríjalo en la configuración. No se utiliza un editor de tarjetas independiente en la interfaz.

Página HTML del cliente en lugar de Inicio#

Un administrador puede sustituir el contenido de la página Inicio protegida por un solo archivo HTML. Se conservan la cabecera, el menú lateral, la salida y los permisos del Rol. La página es visible para todas las personas con acceso a Inicio. No incluya secretos ni datos personales en el archivo.

  1. Prepare un archivo frontend/config/custom-home/index.html. Coloque el contenido visible en body y los estilos en un elemento style de head o en atributos style. Ejemplo:

    <!doctype html>
    <html lang="es">
    <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <style>.client-home { max-width: 1200px; margin: auto; padding: 24px; }</style>
    </head>
    <body>
      <main class="client-home">
        <h1>Bienvenido</h1>
        <a href="/main/new-chat">Abrir el Chat</a>
      </main>
    </body>
    </html>
    
  2. En docker-compose.yml, agregue un montaje de solo lectura para el servicio aiserver-nginx:

    services:
      aiserver-nginx:
        volumes:
          - ./frontend/config/custom-home/index.html:/opt/SherpaAIServer/frontend/dist/assets/custom-home/index.html:ro
    
  3. Agregue el campo al archivo frontend/config/branding.json existente, conservando los demás ajustes:

    { "home_html_path": "/assets/custom-home/index.html" }
    
  4. Al activar el montaje por primera vez, vuelva a crear el contenedor nginx con docker compose up -d --force-recreate aiserver-nginx. Inicie sesión y abra /main/home. Tras sustituir el contenido del archivo, actualice la página. El HTML se sirve sin caché.

Página HTML del cliente en Inicio de Sherpa AI Server, interfaz en ruso

Ejemplo de página HTML del cliente en Inicio. Interfaz en ruso.

La ruta debe comenzar por /assets/custom-home/ y terminar con un nombre de archivo HTML, sin subdirectorios. No se admiten URL externas, parámetros de consulta ni ... La página del cliente no debe utilizar JavaScript, formularios, iframe, estilos, fuentes o imágenes externas, ni solicitudes de red desde CSS. Si se necesitan ilustraciones, incorpore SVG o imágenes pequeñas data:image/png, data:image/jpeg o data:image/webp en el mismo HTML. Los elementos y estilos insertados se depuran. El archivo debe adaptarse al área de contenido en teléfono, tableta y ordenador, sin desplazamiento horizontal.

Utilice enlaces normales /main/... para las secciones de Sherpa AI Server. Se abren en la aplicación con las comprobaciones de permisos habituales. Si falta el ajuste, la ruta no es válida o el archivo no está disponible, aparece la página Inicio estándar. Para revertir el cambio, quite home_html_path o asigne null y actualice la página. Después puede retirar el montaje.