Prompt 配置

生成式 AI（GenAI）用于把视觉事件转换成自然语言描述、Review 总结或聊天回答。Securex NVR 支持把云端 OpenAI 兼容接口和本地 AI 服务器作为 Provider；推荐把 API Key 放在环境变量，不要直接写入公开配置或截图。

Provider 与 roles

role	用途
chat	供聊天/问答接口调用。
descriptions	为对象/事件生成描述。
embeddings	用于需要向量嵌入的语义检索能力（具体取决于版本/Provider）。

OpenAI 兼容示例

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

中文描述

如果模型默认输出英文，可在对象描述 Prompt 或 Review Prompt 中明确要求“仅使用简体中文回答，不要输出英文解释”。preferred_language 只影响支持该选项的功能，不能替代 Prompt 对输出格式的约束。

本地 AI

本地 Provider 适合离线和隐私场景，但必须确认模型具备视觉能力，且 API 路径与 OpenAI 兼容层一致。仅能文本聊天的模型无法从事件截图生成可靠视觉描述。

排错

错误	常见原因
401/403	API Key、认证头或反向代理鉴权错误。
404	base_url 或兼容接口路径错误。
500	Provider 上游错误、模型加载失败、输入格式不支持。
一直生成中	模型下载未完成、视觉模型不支持、超时、GPU/内存不足。
描述语言不对	检查 Prompt、模型语言能力与调用到的实际 Provider。

建议验证流程

先用 Provider 自身接口验证文本请求。
再验证带单张图片的视觉请求。
然后启用 descriptions。
最后再启用 Review 总结、聊天和语义能力，避免同时排查多个链路。

Prompt Configuration

Generative AI converts visual events into natural-language descriptions, Review summaries, or chat answers. Securex NVR can use OpenAI-compatible cloud gateways or local AI providers. Keep API keys in environment variables rather than public configuration or screenshots.

Providers and roles

Role	Purpose
chat	Interactive chat/question answering.
descriptions	Generate descriptions for tracked objects/events.
embeddings	Vector embeddings for semantic features when supported by the selected provider/build.

OpenAI-compatible example

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

Language control

If a model defaults to English, state the desired language explicitly in the object/Review prompt. A preferred-language setting only affects features that honor it; it is not a replacement for prompt-level output constraints.

Local AI

Local providers improve privacy and offline capability, but the selected model must actually support vision and the endpoint must match the expected compatibility API. A text-only model cannot reliably describe event images.

Troubleshooting

Error	Typical cause
401/403	API key, authorization header, or reverse-proxy authentication.
404	Wrong base_url or compatibility route.
500	Upstream provider/model failure or unsupported input.
Generation never finishes	Model download, unsupported vision path, timeout, or insufficient GPU/RAM.
Wrong language	Prompt, model capability, or requests reaching a different provider than expected.

Validation sequence

Test a text request directly against the provider.
Test a single-image vision request.
Enable descriptions.
Add Review summaries, chat, and semantic features only after the base path is reliable.

Configuración de prompts

La IA generativa convierte eventos visuales en descripciones, resúmenes de Review o respuestas de chat. Securex NVR puede usar gateways compatibles con OpenAI o proveedores locales. Guarde las claves en variables de entorno.

Provider y roles

Rol	Uso
chat	Chat y preguntas.
descriptions	Descripciones de objetos/eventos.
embeddings	Vectores para funciones semánticas cuando estén soportadas.

Ejemplo compatible con OpenAI

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

Idioma

Si el modelo responde en inglés, exija explícitamente el idioma en el prompt. preferred_language no sustituye las reglas del prompt.

IA local

Un provider local mejora privacidad, pero el modelo debe soportar visión y el endpoint debe ser compatible. Un modelo solo de texto no puede describir imágenes de eventos de forma fiable.

Diagnóstico

Error	Causa habitual
401/403	Clave o autenticación/proxy.
404	base_url/ruta incorrecta.
500	Fallo del proveedor/modelo.
No termina	Descarga, visión no soportada, timeout o recursos insuficientes.
Idioma incorrecto	Prompt, modelo o provider equivocado.

Secuencia de prueba

Pruebe texto directamente.
Pruebe una imagen.
Active descriptions.
Después active resumen, chat y funciones semánticas.