OpenAI 兼容接口

生成式 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 总结、聊天和语义能力，避免同时排查多个链路。

Openai Compatible

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.

Guía: Openai Compatible

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.