Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.mka1.com/llms.txt

Use this file to discover all available pages before exploring further.

Use este guia quando precisar mostrar qual conta e usuário final fez uma requisição, produzir relatórios de uso por usuário e investigar ações impróprias. A API MKA1 oferece endpoints públicos de uso, cabeçalhos de correlação de requisição em tempo real e campos de observabilidade vinculados ao usuário. Para detalhes dos endpoints, veja a Referência da API e abra o grupo Usage.

​
O que está disponível hoje

A borda da API em tempo real e a pilha de observabilidade expõem os seguintes elementos:
  • As respostas em tempo real incluem X-Request-ID.
  • A configuração Kong ativa usa o plugin correlation-id com header_name: X-Request-ID, echo_downstream: true e generator: uuid#counter.
  • Os logs SigNoz em tempo real incluem userId, externalUserId e userContext.
  • Os ativos existentes do SigNoz incluem os dashboards MKLLM Gateway, Guardrail Dashboard e Sandbox Commands, além das visualizações de logs Sandbox Commands 24h, Sandbox Command Errors 24h e MKLLM Errors.
Exemplos recentes de sistemas em produção:
  • GET /api/v1/llm/responses retornou X-Request-ID: 0736e48b-3d39-48d8-806c-952c907*****#12
  • GET /api/v1/agents retornou X-Request-ID: 0736e48b-3d39-48d8-806c-952c90*****#13
  • Os agregados de 24 horas do SigNoz mostraram valores de externalUserId como docs-pt-br-user com 14 eventos e docs-test-user com 7 eventos
  • Os agregados de 24 horas do SigNoz mostraram valores de userId como dRdj8VeoyuE7P9txS7ZVQ8ixI2***** com 63 eventos e uy95pqlp4ABgWCn5oLikRGV1TT***** com 23 eventos

​
Como isso aparece no nosso dashboard

visualização em lista do SigNoz visualização individual de log

​
Envie um ID de usuário final estável em cada requisição delegada

Para integrações server-side multiusuário, envie tanto o Authorization quanto o X-On-Behalf-Of. É isso que vincula o uso, recursos e logs ao usuário final correto. 
curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "meetkai:functionary-pt",
    "input": "Reply with ok."
  }'
Capture os cabeçalhos de resposta dessa requisição e armazene o X-Request-ID junto com a entrada de log da sua aplicação. Isso fornece uma chave de junção estável entre a borda da API e a observabilidade downstream.

​
Consulte relatórios de uso por usuário

Os endpoints públicos de uso suportam filtros user_ids e dimensões group_by. Use-os para relatórios em nível de conta e, em seguida, utilize os logs do SigNoz para investigar um usuário final ou requisição específica. 
import { SDK } from "@meetkai/mka1";

const mka1 = new SDK({
  bearerAuth: `Bearer ${process.env.MKA1_API_KEY}`,
});

const endTime = Math.floor(Date.now() / 1000);
const startTime = endTime - 24 * 60 * 60;

const usage = await mka1.llm.usage.responses({
  startTime,
  endTime,
  userIds: ["docs-test-user", "docs-pt-br-user"],
  groupBy: ["model", "background"],
});

console.log(usage);
Use userIds para os IDs de usuário final do X-On-Behalf-Of. Por exemplo, a especificação em produção atualmente expõe endpoints de uso para responses, conversations, completions, embeddings, extract, classify e vector stores.

​
Registre ações como um vocabulário fixo de auditoria

A detecção de uso indevido por usuário e por unidade depende dos seus serviços emitirem eventos de ação consistentes. O contrato de auditoria compartilhado em infra-resources define os campos obrigatórios:
  • request_id
  • actor_id
  • unit_id
  • route_name
  • action
  • resource_type
  • resource_id
  • outcome
  • policy_action
{
  "request_id": "0736e48b-3d39-48d8-806c-952c907aa0be#12",
  "actor_id": "docs-test-user",
  "unit_id": "support-team-a",
  "route_name": "POST /api/v1/llm/responses",
  "action": "generate",
  "resource_type": "response",
  "resource_id": "resp_54d14e822fac430396ea2c04f771d7d3",
  "outcome": "success"
}
Se uma política ou guardrail for acionada, registre isso no mesmo evento: 
{
  "action": "tool_call",
  "outcome": "policy_violation",
  "policy_action": "block"
}

​
Detecte ações impróprias

Agrupe seus logs e dashboards por actor_id, unit_id, action, outcome e policy_action. Isso permite responder a duas perguntas diferentes:
  • Qual usuário final ou unidade gerou a atividade?
  • Quais ações foram negadas, limitadas ou bloqueadas por política?
O contrato de infraestrutura em produção atualmente define estes resultados:
  • success
  • denied
  • throttled
  • validation_error
  • policy_violation
Os valores correspondentes de policy_action são:
  • warn
  • block
  • escalate
Um exemplo real já visível no SigNoz em 30 de março de 2026 mostra limitação em tempo de execução de atividade de ferramenta no mkllm-gateway:
  • mensagem: Limiting parallel tool calls to respect max_tool_calls
  • requestedToolCalls: 2
  • allowedToolCalls: 1
  • maxToolCalls: 5
  • responseId: resp_bcc0e8bba9524e8d9c14289c0c6*****
Esse padrão é útil para detecção de ações impróprias porque mostra a quantidade de ações tentadas e permitidas no mesmo evento.

​
Fluxo prático de investigação

Ao investigar uma requisição suspeita, siga esta ordem:
  1. Comece pelo relatório de uso em nível de conta nos endpoints de uso da Referência da API.
  2. Restrinja ao usuário final por X-On-Behalf-Of e externalUserId.
  3. Use o X-Request-ID para correlacionar a requisição exata na borda.
  4. Inspecione os logs do SigNoz para userId, externalUserId, userContext, route_name, action e outcome.
  5. Verifique os dashboards MKLLM Gateway, Guardrail Dashboard e Sandbox Commands para atividades de política ou ferramenta relacionadas.
Isso fornece um caminho consistente desde o relatório de uso até uma requisição específica e, então, até o evento de ação exato que foi permitido, alertado, bloqueado ou escalado.