生成式 AI（GenAI）

GenAI 为 Securex NVR 提供自然语言描述、Review 总结、视觉问答和语义搜索等能力。Provider 只是“可用的模型服务”；要真正产生描述，还必须分别启用 objects.genai 或 review.genai 等功能。

Provider 与 Roles

genai 是命名 Provider 的映射。每个 Provider 可以承担 chat、descriptions、embeddings 中一个或多个 role。一个 role 应只由一个 Provider 负责。

genai:
  agnes:
    provider: openai
    api_key: ${GENAI_API_KEY}
    model: agnes-2.0-flash
    base_url: https://apihub.example.com/v1
    roles:
      - chat
      - descriptions
    provider_options:
      context_size: 256000

三个 Role 的区别

Role	用途	模型要求
descriptions	目标描述、Review 摘要	需要视觉理解能力
chat	对画面/事件进行对话式询问	通常需要视觉模型
embeddings	语义搜索向量	必须是为图文检索训练的 embedding 模型

启用目标描述

objects:
  genai:
    enabled: true
    prompt: >-
      仅使用简体中文描述画面中的目标、动作和重要环境信息。
      不要猜测无法从画面确认的身份、年龄或意图。

本地 AI

本地 Provider 可以把图像和提示词保留在服务器内部，但视觉模型对 GPU/显存要求明显高于普通文本模型。CPU-only 可以用于功能验证，但实时体验通常较差。Local AI Chat 插件应明确显示模型下载、加载、显存占用与生成状态。

故障定位

401/403：API Key、Authorization header 或反向代理认证。
404：base_url 或 endpoint 不兼容。
500：模型服务内部错误、上下文/图片格式或代理失败。
一直卡住：先直接请求 Provider API，确认模型能在不经过 NVR UI 时返回。
Provider 正常但没有描述：检查 descriptions role，以及 objects.genai/review.genai 是否启用。

中文输出

“preferred_language”或 Prompt 只能指导模型语言，并不能修复不支持视觉输入的模型。若模型能看图但偶尔输出英文，可在 Prompt 中明确“仅使用简体中文回答”，并避免中英混合的模板文本。

Generative AI (GenAI)

GenAI powers natural-language descriptions, Review summaries, visual chat, and semantic-search related workflows. Configuring a provider only makes a model service available; object or Review generation must still be enabled separately.

Providers and roles

genai is a map of named providers. A provider can handle one or more of chat, descriptions, and embeddings. Assign each role to only one provider.

genai:
  agnes:
    provider: openai
    api_key: ${GENAI_API_KEY}
    model: agnes-2.0-flash
    base_url: https://apihub.example.com/v1
    roles: [chat, descriptions]
    provider_options:
      context_size: 256000

Role differences

Role	Purpose	Model
descriptions	Object descriptions and Review summaries	Vision-capable
chat	Conversational questions about images/events	Usually vision-capable
embeddings	Semantic search vectors	Multimodal retrieval embedding model

Object descriptions

objects:
  genai:
    enabled: true
    prompt: >-
      Describe the object's actions and important visible context.
      Do not infer identity, age, or intent that cannot be seen.

Local AI

Local providers keep images/prompts on the server but vision models are demanding. CPU-only is useful for validation but often too slow for interactive use. A local AI plugin should expose model download/load state, memory use, and generation status.

Troubleshooting

401/403: API key, authorization header, or reverse proxy auth.
404: incompatible base URL or endpoint.
500: provider/model failure, image/context issue, or proxy error.
Generation hangs: call the provider API directly first.
Provider works but no description: verify descriptions role and that objects.genai/review.genai is enabled.

Language output

Language preferences and prompts guide output language; they cannot make a text-only model understand images. Use a clear language instruction and a vision-capable model.

IA generativa (GenAI)

GenAI ofrece descripciones, resúmenes de Review, chat visual y flujos relacionados con búsqueda semántica. Configurar un provider no activa automáticamente las funciones de generación.

Providers y roles

genai contiene providers con nombre. Cada uno puede asumir chat, descriptions y/o embeddings. Cada rol debe quedar asignado a un solo provider.

genai:
  agnes:
    provider: openai
    api_key: ${GENAI_API_KEY}
    model: agnes-2.0-flash
    base_url: https://apihub.example.com/v1
    roles: [chat, descriptions]
    provider_options:
      context_size: 256000

Diferencia de roles

Rol	Uso	Modelo
descriptions	Descripciones y resúmenes	Con visión
chat	Preguntas sobre imágenes/eventos	Normalmente con visión
embeddings	Vectores para búsqueda	Embedding multimodal entrenado para retrieval

Descripciones

objects:
  genai:
    enabled: true
    prompt: >-
      Describe las acciones y el contexto visible importante.
      No infieras identidad, edad ni intención.

IA local

Los providers locales mantienen los datos en el servidor, pero los modelos visuales necesitan GPU/memoria. CPU sirve para validar, no siempre para uso interactivo.

Problemas

401/403: clave o autenticación.
404: base_url/endpoint.
500: provider/modelo/proxy.
Bloqueado: pruebe la API del provider directamente.
Provider correcto sin descripción: revise role descriptions y objects.genai/review.genai.

Idioma

El prompt guía el idioma, pero no convierte un modelo de texto en uno visual.