Relatório

Gere um relatório de análise de vídeo enviando a solicitação para um dos dois back-ends — nunca por meio do POST /generate no agente VSS.

Se a solicitação for ambígua (por exemplo, “relatório sobre " sem intervalo de tempo e sem descrição do incidente), use o Modo A como padrão. Pergunte apenas se o usuário mencionar tanto um sensor quanto um intervalo de tempo. Consulte os exemplos abaixo para ver as formulações de solicitação que direcionam para cada modo.

Instruções

1. Escolha o modo — Modo A para um único clipe gravado/vídeo de sensor; Modo B quando a solicitação especificar um intervalo de tempo ou incidentes/alertas (compare com os exemplos).
2. Verifique o perfil de implantação para esse modo em “Pré-requisitos de implantação”; encaminhe para /vss-deploy-profile se a verificação falhar.
3. Execute as etapas numeradas desse modo — Modo A ou Modo B abaixo.
4. Reescreva todas as URLs de clipes voltadas para o usuário com a sequência de uma linha $VSS_PUBLIC_HOST:$VSS_PUBLIC_PORT (URL de clipe reproduzível no navegador) antes de incorporá-las ao relatório.
5. Retorne o Markdown do relatório renderizado ao usuário.

Contrato de saída para avaliadores:

• O título principal do Modo A DEVE ser exatamente # Relatório de Análise de Vídeo.
• O título principal do Modo B DEVE ser exatamente # Relatório de Intervalo de Incidentes (nunca # Relatório de Incidente ou variantes com o nome do sensor).
• O Modo B DEVE incluir ## Informações Básicas com as linhas exatas exigidas pelo modelo (Identificador do Relatório, Intervalo, Escopo, Total de Incidentes, Confirmados / Rejeitados / Não Verificados).

Exemplos

• “Gerar um relatório para este vídeo” / “relatório sobre " → Modo A
• “Analise warehouse_01.mp4” / “crie um relatório de análise sobre o vídeo enviado” → Modo A
• “Relatório sobre incidentes das 12h31Z às 12h32Z” → Modo B
• “Relatório sobre os alertas de hoje” / “quais incidentes ocorreram na última hora” → Modo B
• "Resumir os alertas de entre e " → Modo B

Gatilhos negativos

Não use essa habilidade quando a solicitação for uma das seguintes:

• Perguntas e respostas visuais pontuais sobre um clipe que não solicitem explicitamente um relatório (“de que cor é o caminhão?”, “o que acontece aos 00:12?”) → use /vss-ask-video.
• Recuperação de arquivo/semelhança semântica (“encontre empilhadeiras”, “pesquise todos os vídeos por condução muito próxima”) → use /vss-search-archive.
• Consulta de incidentes/métricas somente para leitura, sem necessidade de geração de relatório → use /vss-query-analytics.
• Implantação/desativação/alterações de perfil (“implantar alertas”, “trocar de perfil”, “ativar a configuração básica”) → use /vss-deploy-profile.
• Solicitações de gerenciamento de alertas/regras em tempo real → use /vss-manage-alerts.

Nunca encaminhe relatórios por meio do POST /generate do VSS-agent.

Pré-requisito de implantação

O Modo A requer o perfil básico do VSS (VST + VLM NIM). O Modo B requer o perfil de alertas do VSS (VA-MCP + Elasticsearch).

Teste:

# Modo A — acessibilidade do VST + VLM
curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/version" >/dev/null

# Modo B — VA-MCP
curl -sf --max-time 5 "http://${HOST_IP}:9901/" >/dev/null

Se o teste falhar, encaminhe para /vss-deploy-profile com -p base (Modo A) ou -p alerts (Modo B). Sempre confirme a implantação com o usuário primeiro.

URLs de clipes: entrada do VLM x link do relatório do navegador

O VST retorna URLs de clipes usando o host:porta interno do agente ${HOST_IP}:30888. Mantenha essa URL original como VIDEO_URL para extrações de quadros do VLM locais ou dentro do cluster. Não reescreva a URL de entrada do VLM apenas para torná-la reproduzível no navegador.

Crie BROWSER_CLIP_URL apenas para URLs exibidas no relatório renderizado. A camada de implantação exporta o host:porta voltado para o navegador como $VSS_PUBLIC_HOST / $VSS_PUBLIC_PORT (e o esquema como $VSS_PUBLIC_HTTP_PROTOCOL) em todos os arquivos .env de perfil — Brev ou bare-metal —, de modo que a reescrita do link do relatório é:

: "${VSS_PUBLIC_HOST:?Defina VSS_PUBLIC_HOST antes de reescrever URLs de clipes}"
: "${VSS_PUBLIC_PORT:?Defina VSS_PUBLIC_PORT antes de reescrever URLs de clipes}"
VSS_PUBLIC_HTTP_PROTOCOL="${VSS_PUBLIC_HTTP_PROTOCOL:-http}"
BROWSER_CLIP_URL=$(echo "$RAW_URL" | sed -E "s|^https?://[^/]+|${VSS_PUBLIC_HTTP_PROTOCOL}://${VSS_PUBLIC_HOST}:${VSS_PUBLIC_PORT}|")

Se algum dos valores obrigatórios do host público estiver faltando, omita o link do clipe no relatório e indique que não foi possível gerar uma URL reproduzível no navegador; não bloqueie o caminho de análise do VLM local. Aplique a reescrita a todas as URLs de clipes exibidas no relatório gerado (Modalidade A, Etapa 4, linha de URL do clipe; Modalidade B, subponto de clipe por incidente). Deixe o bloco de conteúdo video_url do VLM na Modalidade A, Etapa 3, com a URL interna original quando o VLM for local ou estiver no cluster.

Modo A — Relatório sobre um clipe de vídeo gravado

Se o perfil VSS lvs estiver implantado — curl -sf --max-time 5 "http://${HOST_IP}:38111/v1/ready" retorna HTTP 200 — execute /vss-summarize-video para gerar o resumo, em seguida, cole a saída no modelo de relatório na Etapa 4 e pule as Etapas 1–3 (o caminho direto do VLM). Execute as Etapas 1–3 somente quando /v1/ready não retornar 200.

Etapa 1 — Resolver a URL do clipe

Passe para o /vss-manage-video-io-storage para:

1. Listar sensores e confirmar se o sensor nomeado (faça o upload primeiro, caso não existam).

2. Buscar /storage//timelines para o intervalo gravado quando o usuário não forneceu startTime / endTime.

3. Solicitar uma URL do clipe:

   curl -s "http://${HOST_IP}:30888/vst/api/v1/storage/file//url?startTime=&endTime=&container=mp4&disableAudio=true" | jq -r .videoUrl
   

   Isso gera uma URL direta do arquivo MP4 da qual o VLM local ou dentro do cluster pode extrair quadros. Associe-a a VIDEO_URL (usada pelo VLM na Etapa 3) e defina RAW_URL="$VIDEO_URL" antes de aplicar a reescrita do link do relatório para gerar BROWSER_CLIP_URL para a Etapa 4 — o navegador do usuário não consegue acessar $VIDEO_URL diretamente. O Modo A exige que o endpoint VLM selecionado seja capaz de buscar VIDEO_URL. Implantações locais de NIM/RT-VLM normalmente conseguem; endpoints remotos geralmente não conseguem buscar localhost, HOST_IP privado ou URLs internas do VST. Se o VLM_ENDPOINT ativo for remoto, exponha esse requisito de acessibilidade em vez de fazer uma solicitação de chat que falhará após o sucesso de /v1/models.

Etapa 2 — Resolver o endpoint VLM e o modelo

A implantação pode disponibilizar o VLM por meio de uma das duas pilhas. Ambas expõem uma API de bate-papo/completações compatível com a OpenAI — escolha aquela que estiver ativa:

Leia os valores em tempo real do contêiner do agente em execução — não adivinhe:

docker exec vss-agent sh -lc '
para k em HOST_IP VLM_MODE VLM_MODEL_TYPE VLM_BASE_URL VLM_NAME RTVI_VLM_BASE_URL RTVI_VLM_MODEL_TO_USE; faça
  v="$(printenv "$k")"
  [ -n "$v" ] && printf "%s=%s\n" "$k" "$v"
done
'

Não é necessário que RTVI_VLM_ENDPOINT esteja presente no ambiente do vss-agent; vários perfis não o inserem.

Regra de seleção:

if [ "${VLM_MODEL_TYPE:-}" = "rtvi" ]; then
  VLM_BACKEND="rtvlm"
  VLM_ENDPOINT="${RTVI_VLM_BASE_URL:+${RTVI_VLM_BASE_URL%/}/v1}"
  [ -z "${VLM_ENDPOINT}" ] && VLM_ENDPOINT="http://${HOST_IP}:8018/v1"   # alerta padrão
  VLM_MODEL="${RTVI_VLM_MODEL_TO_USE}"
elif [ -n "${VLM_BASE_URL}" ] && [ "${VLM_MODE}" != "none" ]; then
  VLM_BACKEND="nim_cosmos"
  VLM_ENDPOINT="${VLM_BASE_URL%/}/v1"
  VLM_MODEL="${VLM_NAME}"
else
  VLM_BACKEND="rtvlm"
  VLM_ENDPOINT="${RTVI_VLM_BASE_URL:+${RTVI_VLM_BASE_URL%/}/v1}"
  [ -z "${VLM_ENDPOINT}" ] && VLM_ENDPOINT="http://${HOST_IP}:30082/v1"  # padrão básico
  VLM_MODEL="${RTVI_VLM_MODEL_TO_USE}"
fi

Verifique /v1/models antes de enviar uma solicitação de chat para confirmar se o endpoint escolhido está ativo e se o modelo está carregado:

curl -sf --max-time 5 "${VLM_ENDPOINT}/models" | jq -r '.data[].id'

Se a verificação falhar ou se os IDs listados não incluírem ${VLM_MODEL}, recorra ao outro backend (ou exiba o erro — nunca escolha silenciosamente um modelo que não esteja no servidor).

Etapa 3 — Chame o VLM diretamente

Use o endpoint de chat/completações compatível com a OpenAI com um bloco de conteúdo video_url — o mesmo formato de carga útil e as mesmas configurações multimodais que o video_understanding constrói em src/vss_agents/tools/video_understanding.py (_build_vlm_messages + a chamada base_vlm.bind(...) do Cosmos).

A amostragem de quadros e o orçamento de tokens visuais (pixels) devem corresponder às configurações do video_understanding em tempo real para o perfil ativo. Envie mm_processor_kwargs e media_io_kwargs para que a chamada direta use a mesma amostragem de quadros e o mesmo orçamento de pixels que a ferramenta video_understanding no agente — omitir esses parâmetros permite que o VLM aplique seus próprios padrões, fazendo com que a saída diverja do caminho do agente.

PROMPT='Descreva em detalhes o que acontece no vídeo, com marcas de tempo (início–fim em segundos a partir do início do clipe) para cada segmento ou evento. Aborde cenas, objetos, pessoas, veículos e ações notáveis.'

# O raciocínio está DESATIVADO por padrão — corresponde à configuração do perfil básico do `video_understanding` (`reasoning: false`).
# O `video_understanding.py` usa `config.reasoning`, a menos que o chamador o substitua; portanto, o padrão é sem raciocínio.
# Acrescente o sufixo de raciocínio Cosmos Reason 2 SOMENTE quando o usuário solicitar explicitamente o raciocínio
# (omita-o para VLMs que não sejam Cosmos Reason 2). Com o raciocínio desativado, a resposta não contém  o bloco .
if [ "${REASONING:-false}" = "true" ]; then
PROMPT="${PROMPT}

Responda à pergunta usando o seguinte formato:


Seu raciocínio.


Escreva sua resposta final imediatamente após a  tag ."
fi

# Se a Etapa 3 for executada de forma independente, determine o backend ausente a partir do ambiente/modelo atual.
[ -z "${VLM_BACKEND:-}" ] && {
  if [ "${VLM_MODEL_TYPE:-}" = "rtvi" ]; then
    VLM_BACKEND="rtvlm"
  elif [[ "${VLM_MODEL:-}" == nvidia/cosmos* ]]; then
    VLM_BACKEND="nim_cosmos"
  else
    VLM_BACKEND="rtvlm"
  fi
}

# Configurações multimodais — determinar a partir do caminho do arquivo de configuração do agente ativo, e não de opções pré-definidas.
CFG_JSON=$(
docker exec vss-agent python3 -c '
import json, os, yaml
p = os.getenv("VSS_AGENT_CONFIG_FILE")
if not p:
    raise SystemExit("VSS_AGENT_CONFIG_FILE não está definido no vss-agent")
if not os.path.isabs(p):
    p = os.path.join("/vss-agent", p.lstrip("./"))
with open(p, encoding="utf-8") as f:
    cfg = yaml.safe_load(f) or {}
vu = (cfg.get("functions", {}) ou {}).get("video_understanding", {}) ou {}
print(json.dumps({
    "max_fps": int(vu.get("max_fps", 2)),
    "max_frames": int(vu.get("max_frames", 30)),
    "min_pixels": int(vu.get("min_pixels", 3136)),
    "max_pixels": int(vu.get("max_pixels", 8388608)),
}))
')
)
[ -n "${CFG_JSON}" ] || { echo "Falha ao ler a configuração do video_understanding do vss-agent"; exit 1; }
jq -e . >/dev/null <<< "${CFG_JSON}" || { echo "JSON de configuração inválido do vss-agent"; exit 1; }
MAX_FPS="$(jq -r '.max_fps' <<< "${CFG_JSON}")"
MAX_FRAMES="$(jq -r '.max_frames' <<< "${CFG_JSON}")"
MIN_PIXELS="$(jq -r '.min_pixels' <<< "${CFG_JSON}")"
MAX_PIXELS="$(jq -r '.max_pixels' <<< "${CFG_JSON}")"

# num_frames = min(int(clip_seconds) * max_fps, max_frames), mínimo 1 — corresponde ao video_understanding.py.
# clip_seconds (Step 1 endTime-startTime) pode conter frações; arredondar para segundos inteiros — o bash $((...))
# aceita apenas números inteiros e gera erro com "15,0"/"1,5". Padrão 15 s -> limitado a MAX_FRAMES.
CLIP_SECONDS=$(awk -v s="${CLIP_SECONDS:-15}" 'BEGIN{printf "%d", s}')
NUM_FRAMES=$(( CLIP_SECONDS * MAX_FPS ))
[ "$NUM_FRAMES" -gt "$MAX_FRAMES" ] && NUM_FRAMES=$MAX_FRAMES
[ "$NUM_FRAMES" -lt 1 ] && NUM_FRAMES=1

# Aplique os argumentos de linha de comando do Cosmos mm/media apenas no caminho do NIM Cosmos.
# O modo RT-VLM usa seu próprio pré-processamento do lado do servidor e não deve receber esses argumentos de linha de comando.
MM_KWARGS=""
if [ "${VLM_BACKEND}" = "nim_cosmos" ]; then
  case "$VLM_MODEL" in
    *cosmos-reason2*) MM_KWARGS=", \"mm_processor_kwargs\": {\"size\": {\"shortest_edge\": ${MIN_PIXELS}, \"longest_edge\": ${MAX_PIXELS}}}, \"media_io_kwargs\": {\"video\": {\"num_frames\": ${NUM_FRAMES}}}" ;;
    *cosmos*)         MM_KWARGS=", \"mm_processor_kwargs\": {\"videos_kwargs\": {\"min_pixels\": ${MIN_PIXELS}, \"max_pixels\": ${MAX_PIXELS}}}, \"media_io_kwargs\": {\"video\": {\"num_frames\": ${NUM_FRAMES}}}" ;;
    *)                      MM_KWARGS="" ;;
  esac
fi

curl -s --connect-timeout 5 --max-time 120 -X POST "${VLM_ENDPOINT}/chat/completions" \
  -H "Content-Type: application/json" \
  -d @- <<EOF | jq -r '.choices[0].message.content'
{
  "model": $(jq -Rs . <<< "${VLM_MODEL}"),
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": $(jq -Rs . <<< "${PROMPT}")},
        {"type": "video_url", "video_url": {"url": $(jq -Rs . <<< "${VIDEO_URL}")}}
      ]
    }
  ],
  "max_tokens": 1024,
  "temperature": 0.0${MM_KWARGS}
}
EOF

O bloco kwargs é sensível ao backend: no nim_cosmos, as variantes do Reason2 (nvidia/cosmos-reason2*) usam mm_processor_kwargs.size{shortest_edge,longest_edge} e outras variantes do NIM Cosmos (nvidia/cosmos*) usam mm_processor_kwargs.videos_kwargs{min_pixels,max_pixels}; ambos também enviam media_io_kwargs.video.num_frames. No rtvlm, nenhum kwargs do Cosmos é enviado.

Se o VLM retornar um … (modo de raciocínio Cosmos Reason), mantenha apenas o texto após como corpo do relatório.

Etapa 4 — Preencha o modelo do Relatório de Análise de Vídeo

Copie o arquivo assets/video-analysis-report.md, preencha todos os espaços reservados e retorne o Markdown renderizado ao usuário. Mantenha o arquivo original inalterado. Antes da renderização, verifique se BROWSER_CLIP_URL está definido e não está vazio; em seguida, substitua por esse valor exato na linha “URL do clipe ”. Nunca deixe o espaço reservado na saída, nunca inclua instruções do modelo em uma célula preenchida e nunca use a URL bruta HOST_IP:30888.

Modo B — Relatório sobre incidentes em um intervalo de tempo

Etapa 1 — Defina o intervalo de tempo e (opcionalmente) o sensor

• start_time / end_time devem estar no formato ISO 8601 UTC (AAAA-MM-DDTHH:MM:SS.sssZ). Resolva expressões relativas (“última hora”, “hoje”) com base no relógio atual do host.
• Se o usuário especificar um sensor, registre-o como source + source_type=sensor. Caso contrário, deixe ambos em branco para uma consulta que abranja todos os sensores.

Etapa 2 — Obter incidentes via /vss-query-analytics

Encaminhe para /vss-query-analytics (inicializar → tools/call) com:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "video_analytics__get_incidents",
    "arguments": {
      "source": "",
      "source_type": "sensor",
      "start_time": "",
      "end_time": "",
      "max_count": 100,
      "includes": ["objectIds", "info"]
    }
  },
  "id": 1
}

Limite de somente leitura (obrigatório):

• O Modo B é estritamente para recuperação de análises somente leitura. Nunca grave, insira dados iniciais, preencha retroativamente ou altere dados do Elasticsearch/VA.
• Exemplos proibidos: indexar incidentes sintéticos, reproduzir cargas úteis de fixtures no ES, chamar APIs de gravação/atualização/exclusão para “disponibilizar dados” para o relatório.
• Se não houver incidentes para o intervalo/escopo solicitado, trate como resultados vazios (veja abaixo); não invente dados.

Para cada incidente, mantenha: id, sensorId, timestamp, end, category, place.name, info.verdict, info.reasoning, objectIds e a URL do clipe (geralmente info.clip_url, clip_url ou qualquer campo de ponteiro de clipe que a resposta contenha). Aplique a reescrita $VSS_PUBLIC_HOST:$VSS_PUBLIC_PORT (consulte “URL do clipe reproduzível no navegador” acima) a cada URL de clipe antes de colá-la no relatório — o valor bruto é uma URL do tipo HOST_IP:30888 que o navegador do usuário não consegue acessar.

Etapa 3 — Preencha o modelo de Relatório de Intervalo de Incidentes

Copie o arquivo assets/incident-range-report.md, depois agrupe por sensor (ou por categoria, se não houver escopo de sensor), some os veredictos e liste cada incidente com data e hora / categoria / veredicto / justificativa. Mantenha o arquivo original inalterado. Cada valor de clipe de incidente deve ser uma URL reescrita e reproduzível no navegador; omita a linha do clipe quando o incidente não contiver nenhuma URL de clipe. Nunca inclua instruções do modelo em uma célula preenchida.

Se get_incidents retornar zero resultados, PARE e retorne exatamente uma declaração de intervalo vazio de uma linha, indicando o intervalo e o escopo solicitados. Não renderize o modelo completo de Intervalo de Incidentes, não invente incidentes, não insira dados de teste e não recorra ao Modo A.

Tratamento de erros

• Se uma sonda, um curl, uma chamada VLM ou uma solicitação /vss-query-analytics falhar, interrompa o fluxo de trabalho e relate o endpoint com falha, o status HTTP ou o erro de comando, além da próxima etapa útil de recuperação. Não crie um relatório a partir de dados parciais ou ausentes.
• Se a resposta do VLM estiver vazia, malformada ou contiver apenas um bloco de justificativa, destaque esse problema na resposta e sugira a verificação da prontidão do modelo e dos logs antes de tentar novamente.
• Se uma URL de clipe não puder ser reescrita para o host/porta pública, omita-a do relatório gerado e indique que não foi possível produzir a URL reproduzível no navegador.
• Para o Modo B, trate os campos opcionais de incidente ausentes (info.reasoning, objectIds, URL do clipe) como omissões no relatório, mas trate a ausência de id, carimbo de data/hora ou categoria como um erro de qualidade de dados que deve ser relatado.

Referência cruzada

• /vss-manage-video-io-storage — lista de sensores, linhas do tempo e URL do clipe para a Etapa 1 do Modo A.
• /vss-query-analytics — recuperação de incidentes (e enriquecimento de veredicto/raciocínio) para a Etapa 2 do Modo B.
• /vss-ask-video — perguntas e respostas ad hoc do VLM sobre um único clipe (não é um relatório estruturado).
• /vss-summarize-video — usado pelo Modo A para gerar o corpo do resumo quando o perfil lvs é implantado; o modelo de relatório (Etapa 4) ainda é preenchido aqui.