+10
-10
@@ -2,16 +2,16 @@
|
||||
|
||||
Base `/api/v1/ai`. Autenticação por sessão Laravel, email verificado, `manage-portal`, feature flag e CSRF do middleware web. Não é API OAuth/OIDC para terceiros. Enviar `Accept: application/json`; o React usa as rotas equivalentes `/management/ai` via Inertia.
|
||||
|
||||
| Método / recurso | Entrada | Resultado |
|
||||
| --- | --- | --- |
|
||||
| POST `/runs` | capability, purpose, language; query para assistant/search; source_id para summary; interest_id para classify; sector_id/province/maturity_level opcionais para recommend; source_id/nature opcionais para search | 201 com UUID; finalidade verificada também pelo gateway |
|
||||
| GET `/runs/{uuid}` | UUID | Metadados e resultado, ou resultado nulo quando fonte/consentimento revogados ou capacidade suspensa |
|
||||
| POST `/runs/{uuid}/feedback` | rating: helpful/unhelpful/unsafe; review_requested boolean | Feedback idempotente por utilizador/resultado; unsafe suspende a capacidade |
|
||||
| POST `/runs/{uuid}/review` | status: accepted/rejected; version_no | Revisão independente, conflito 409 em versão antiga; nenhum envio externo |
|
||||
| POST `/documents` | Multipart file texto simples, authorised=true | 201 document_id canónico; não torna a fonte pesquisável |
|
||||
| POST `/sources` | document_id, title, language pt/en, nature, source_url HTTPS, source_owner, evidence_reference, source_date, valid_until, authorised=true | Fonte pendente e fragmentos indexados, ainda inelegíveis |
|
||||
| POST `/sources/{uuid}/review` | status: approved/revoked; expected_status | Confirmação por outra pessoa para aprovar; conflito se estado mudou |
|
||||
| POST `/controls/{capability}` | suspended boolean | Suspensão imediata no armazenamento partilhado; fora do limite de consultas, mantendo autorização/CSRF |
|
||||
| Método / recurso | Entrada | Resultado |
|
||||
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
|
||||
| POST `/runs` | capability, purpose, language; query para assistant/search; source_id para summary; interest_id para classify; sector_id/province/maturity_level opcionais para recommend; source_id/nature opcionais para search | 201 com UUID; finalidade verificada também pelo gateway |
|
||||
| GET `/runs/{uuid}` | UUID | Metadados e resultado, ou resultado nulo quando fonte/consentimento revogados ou capacidade suspensa |
|
||||
| POST `/runs/{uuid}/feedback` | rating: helpful/unhelpful/unsafe; review_requested boolean | Feedback idempotente por utilizador/resultado; unsafe suspende a capacidade |
|
||||
| POST `/runs/{uuid}/review` | status: accepted/rejected; version_no | Revisão independente, conflito 409 em versão antiga; nenhum envio externo |
|
||||
| POST `/documents` | Multipart file texto simples, authorised=true | 201 document_id canónico; não torna a fonte pesquisável |
|
||||
| POST `/sources` | document_id, title, language pt/en, nature, source_url HTTPS, source_owner, evidence_reference, source_date, valid_until, authorised=true | Fonte pendente e fragmentos indexados, ainda inelegíveis |
|
||||
| POST `/sources/{uuid}/review` | status: approved/revoked; expected_status | Confirmação por outra pessoa para aprovar; conflito se estado mudou |
|
||||
| POST `/controls/{capability}` | suspended boolean | Suspensão imediata no armazenamento partilhado; fora do limite de consultas, mantendo autorização/CSRF |
|
||||
|
||||
Capacidades: assistant, search, recommend, classify, quality, sla, summary. Finalidades: investment_information para pesquisa/recomendação/excertos; interest_triage para triagem; data_quality e execution_monitoring para monitores.
|
||||
|
||||
|
||||
@@ -30,15 +30,15 @@ O React apenas comunica com Laravel. A primeira interface é interna, para gesto
|
||||
|
||||
## 3. Linha de base dos sete casos
|
||||
|
||||
| Caso | Execução inicial | Limite explícito |
|
||||
| --- | --- | --- |
|
||||
| UC-IA-001 | Recuperar excertos autorizados com fonte, data, natureza e recusa sem resultados | Sem resposta generativa ou aconselhamento jurídico/financeiro |
|
||||
| UC-IA-002 | Full-text search PT/EN, filtros de fontes e acesso antes da recuperação | Híbrido/embeddings/reranker exigem infraestrutura e benchmark |
|
||||
| Caso | Execução inicial | Limite explícito |
|
||||
| --------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|
||||
| UC-IA-001 | Recuperar excertos autorizados com fonte, data, natureza e recusa sem resultados | Sem resposta generativa ou aconselhamento jurídico/financeiro |
|
||||
| UC-IA-002 | Full-text search PT/EN, filtros de fontes e acesso antes da recuperação | Híbrido/embeddings/reranker exigem infraestrutura e benchmark |
|
||||
| UC-IA-003 | Correspondência estruturada com oportunidades publicadas, factores, lacunas de informação e regras versionadas | Sem previsão de retorno, pontuação financeira ou inferência sensível |
|
||||
| UC-IA-004 | Regras sobre campos declarados da manifestação, sem usar nome/email/telefone | Não altera lead, prioridade ou responsável oficial |
|
||||
| UC-IA-005 | Alertas sobre campos, fontes expiradas e responsáveis | Nenhuma correcção automática de dados |
|
||||
| UC-IA-006 | Prazos vencidos de tarefas CRM abertas | Sem caminho crítico ou impacto orçamental inventado |
|
||||
| UC-IA-007 | Excertos de documentos autorizados | Não constitui resumo generativo completo nem acta oficial |
|
||||
| UC-IA-004 | Regras sobre campos declarados da manifestação, sem usar nome/email/telefone | Não altera lead, prioridade ou responsável oficial |
|
||||
| UC-IA-005 | Alertas sobre campos, fontes expiradas e responsáveis | Nenhuma correcção automática de dados |
|
||||
| UC-IA-006 | Prazos vencidos de tarefas CRM abertas | Sem caminho crítico ou impacto orçamental inventado |
|
||||
| UC-IA-007 | Excertos de documentos autorizados | Não constitui resumo generativo completo nem acta oficial |
|
||||
|
||||
## 4. Segurança e governação
|
||||
|
||||
|
||||
@@ -1,21 +1,82 @@
|
||||
{
|
||||
"executed_at": "2026-09-26T15:51:08+00:00",
|
||||
"backend": "PostgreSQL FTS",
|
||||
"model": null,
|
||||
"synthetic": true,
|
||||
"passed": 8,
|
||||
"cases": 8,
|
||||
"repetitions_per_case": 5,
|
||||
"measurements": [
|
||||
{"language":"pt","query":"formação técnica","expected_match":true,"passed":true,"p50_ms":1.604,"max_ms":8.87},
|
||||
{"language":"pt","query":"cadeia logística","expected_match":true,"passed":true,"p50_ms":1.228,"max_ms":1.551},
|
||||
{"language":"pt","query":"energia solar","expected_match":true,"passed":true,"p50_ms":1.207,"max_ms":1.724},
|
||||
{"language":"pt","query":"taxa oficial","expected_match":false,"passed":true,"p50_ms":1.091,"max_ms":1.457},
|
||||
{"language":"en","query":"vocational training","expected_match":true,"passed":true,"p50_ms":1.237,"max_ms":1.518},
|
||||
{"language":"en","query":"logistics corridor","expected_match":true,"passed":true,"p50_ms":1.233,"max_ms":1.3},
|
||||
{"language":"en","query":"solar energy","expected_match":true,"passed":true,"p50_ms":1.23,"max_ms":1.426},
|
||||
{"language":"en","query":"official tax","expected_match":false,"passed":true,"p50_ms":1.167,"max_ms":1.337}
|
||||
],
|
||||
"generative_benchmark": "not_executed_no_runtime_or_model",
|
||||
"limitations": ["small_single_source_cases", "not_a_representative_benchmark", "not_human_validated_PT_MZ", "no_concurrency_or_load_test"]
|
||||
"executed_at": "2026-09-26T15:51:08+00:00",
|
||||
"backend": "PostgreSQL FTS",
|
||||
"model": null,
|
||||
"synthetic": true,
|
||||
"passed": 8,
|
||||
"cases": 8,
|
||||
"repetitions_per_case": 5,
|
||||
"measurements": [
|
||||
{
|
||||
"language": "pt",
|
||||
"query": "formação técnica",
|
||||
"expected_match": true,
|
||||
"passed": true,
|
||||
"p50_ms": 1.604,
|
||||
"max_ms": 8.87
|
||||
},
|
||||
{
|
||||
"language": "pt",
|
||||
"query": "cadeia logística",
|
||||
"expected_match": true,
|
||||
"passed": true,
|
||||
"p50_ms": 1.228,
|
||||
"max_ms": 1.551
|
||||
},
|
||||
{
|
||||
"language": "pt",
|
||||
"query": "energia solar",
|
||||
"expected_match": true,
|
||||
"passed": true,
|
||||
"p50_ms": 1.207,
|
||||
"max_ms": 1.724
|
||||
},
|
||||
{
|
||||
"language": "pt",
|
||||
"query": "taxa oficial",
|
||||
"expected_match": false,
|
||||
"passed": true,
|
||||
"p50_ms": 1.091,
|
||||
"max_ms": 1.457
|
||||
},
|
||||
{
|
||||
"language": "en",
|
||||
"query": "vocational training",
|
||||
"expected_match": true,
|
||||
"passed": true,
|
||||
"p50_ms": 1.237,
|
||||
"max_ms": 1.518
|
||||
},
|
||||
{
|
||||
"language": "en",
|
||||
"query": "logistics corridor",
|
||||
"expected_match": true,
|
||||
"passed": true,
|
||||
"p50_ms": 1.233,
|
||||
"max_ms": 1.3
|
||||
},
|
||||
{
|
||||
"language": "en",
|
||||
"query": "solar energy",
|
||||
"expected_match": true,
|
||||
"passed": true,
|
||||
"p50_ms": 1.23,
|
||||
"max_ms": 1.426
|
||||
},
|
||||
{
|
||||
"language": "en",
|
||||
"query": "official tax",
|
||||
"expected_match": false,
|
||||
"passed": true,
|
||||
"p50_ms": 1.167,
|
||||
"max_ms": 1.337
|
||||
}
|
||||
],
|
||||
"generative_benchmark": "not_executed_no_runtime_or_model",
|
||||
"limitations": [
|
||||
"small_single_source_cases",
|
||||
"not_a_representative_benchmark",
|
||||
"not_human_validated_PT_MZ",
|
||||
"no_concurrency_or_load_test"
|
||||
]
|
||||
}
|
||||
|
||||
@@ -2,29 +2,29 @@
|
||||
|
||||
## Casos do pedido
|
||||
|
||||
| Caso | Implementado nesta etapa | Pendente |
|
||||
| --- | --- | --- |
|
||||
| UC-IA-001 | Excertos citados de fontes elegíveis, data/natureza, recusa sem evidência e pedido de revisão | Respostas generativas fundamentadas, corpus oficial, assistência pública |
|
||||
| UC-IA-002 | FTS PT/EN, idioma, fonte, natureza e acesso antes da recuperação; fusão RRF unitariamente testada | Embeddings, índice pgvector, reranker e filtros territoriais/multidimensionais completos; RRF ainda não ligado a vectores reais |
|
||||
| UC-IA-003 | Filtros eliminatórios de publicação/sector/província/maturidade, factores e dados em falta; apenas oportunidades canónicas publicadas | Perfil completo, regras institucionais aprovadas, similitude semântica, clusters/corredores/instrumentos/parceiros; pontuação actual conta filtros, não é ponderação financeira |
|
||||
| UC-IA-004 | Triagem por campos declarados, consentimento específico, sem dados de contacto ou texto livre; não altera pedido/lead | Modelo supervisionado, responsável sugerido, idioma/cluster/corredor/horizonte e regras de prioridade aprovadas |
|
||||
| UC-IA-005 | Fontes expiradas, documentos com checksum repetido, ausência de responsável/próxima acção, geometrias inválidas; alertas em resultados auditados | Conflitos semânticos entre fontes, sincronização SuiteCRM e cobertura de todos os domínios |
|
||||
| UC-IA-006 | Tarefas CRM abertas e vencidas, prazo, referência e acção de revisão sugerida | Marcos/dependências, caminho crítico, impacto e orçamento autorizado |
|
||||
| UC-IA-007 | Pré-visualização extractiva dos primeiros três fragmentos de fonte elegível | Resumo generativo completo, reuniões/actas/históricos e extracção de compromissos confirmados |
|
||||
| Caso | Implementado nesta etapa | Pendente |
|
||||
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| UC-IA-001 | Excertos citados de fontes elegíveis, data/natureza, recusa sem evidência e pedido de revisão | Respostas generativas fundamentadas, corpus oficial, assistência pública |
|
||||
| UC-IA-002 | FTS PT/EN, idioma, fonte, natureza e acesso antes da recuperação; fusão RRF unitariamente testada | Embeddings, índice pgvector, reranker e filtros territoriais/multidimensionais completos; RRF ainda não ligado a vectores reais |
|
||||
| UC-IA-003 | Filtros eliminatórios de publicação/sector/província/maturidade, factores e dados em falta; apenas oportunidades canónicas publicadas | Perfil completo, regras institucionais aprovadas, similitude semântica, clusters/corredores/instrumentos/parceiros; pontuação actual conta filtros, não é ponderação financeira |
|
||||
| UC-IA-004 | Triagem por campos declarados, consentimento específico, sem dados de contacto ou texto livre; não altera pedido/lead | Modelo supervisionado, responsável sugerido, idioma/cluster/corredor/horizonte e regras de prioridade aprovadas |
|
||||
| UC-IA-005 | Fontes expiradas, documentos com checksum repetido, ausência de responsável/próxima acção, geometrias inválidas; alertas em resultados auditados | Conflitos semânticos entre fontes, sincronização SuiteCRM e cobertura de todos os domínios |
|
||||
| UC-IA-006 | Tarefas CRM abertas e vencidas, prazo, referência e acção de revisão sugerida | Marcos/dependências, caminho crítico, impacto e orçamento autorizado |
|
||||
| UC-IA-007 | Pré-visualização extractiva dos primeiros três fragmentos de fonte elegível | Resumo generativo completo, reuniões/actas/históricos e extracção de compromissos confirmados |
|
||||
|
||||
Nenhum caso é declarado integralmente concluído. A aceitação da revisão apenas grava um parecer interno. Não altera estados oficiais, cria compromissos ou transmite dados ao SuiteCRM.
|
||||
|
||||
## Pipeline RAG de 17 passos
|
||||
|
||||
| Passos | Situação |
|
||||
| --- | --- |
|
||||
| 1–2: recepção e segurança | Cadastro canónico, upload apenas texto UTF-8, limite de tamanho, confirmação de autorização, rejeição de fontes confidenciais/restritas; formatos complexos/OCR/antivírus pendentes |
|
||||
| Passos | Situação |
|
||||
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1–2: recepção e segurança | Cadastro canónico, upload apenas texto UTF-8, limite de tamanho, confirmação de autorização, rejeição de fontes confidenciais/restritas; formatos complexos/OCR/antivírus pendentes |
|
||||
| 3–6: extracção, versão, acesso e fragmentação | Texto simples, versão/checksum do documento, metadados de fonte, revisão independente, fragmentos com ID/checksum/posição; divisão por caracteres não substitui tokenização do modelo |
|
||||
| 7–8: embeddings e pgvector | Não executados. Extensão/runtime ausentes. Esquema proposto separado, sem tocar na base partilhada |
|
||||
| 9–10: índice lexical e ACL | tsvector gerado por idioma, GIN; status, validade, classificação, versão e checksum filtrados antes da pesquisa |
|
||||
| 11–12: híbrido e reranking | Algoritmo RRF testado isoladamente; corpus vectorial/modelos não provisionados, logo produção continua lexical |
|
||||
| 13–15: contexto, geração e suporte | Excertos devolvidos como citações; sem geração nem afirmações novas. Verificação semântica de afirmações depende de modelo e avaliação |
|
||||
| 16–17: fontes e rastreabilidade | Fonte/data/natureza/validade, modo, regras, versão de instrução e latência; resultado encriptado; sem falsa confiança probabilística |
|
||||
| 7–8: embeddings e pgvector | Não executados. Extensão/runtime ausentes. Esquema proposto separado, sem tocar na base partilhada |
|
||||
| 9–10: índice lexical e ACL | tsvector gerado por idioma, GIN; status, validade, classificação, versão e checksum filtrados antes da pesquisa |
|
||||
| 11–12: híbrido e reranking | Algoritmo RRF testado isoladamente; corpus vectorial/modelos não provisionados, logo produção continua lexical |
|
||||
| 13–15: contexto, geração e suporte | Excertos devolvidos como citações; sem geração nem afirmações novas. Verificação semântica de afirmações depende de modelo e avaliação |
|
||||
| 16–17: fontes e rastreabilidade | Fonte/data/natureza/validade, modo, regras, versão de instrução e latência; resultado encriptado; sem falsa confiança probabilística |
|
||||
|
||||
## Metadados
|
||||
|
||||
|
||||
@@ -2,15 +2,15 @@
|
||||
|
||||
Consulta de fontes primárias em 26/09/2026. São candidatos identificados, não alegações de versões mais recentes nem selecção final. Licença do modelo não elimina obrigações de proveniência dos dados nem valida juridicamente o uso em Moçambique.
|
||||
|
||||
| Candidato fixado para avaliação | Licença declarada | Recursos e decisão |
|
||||
| --- | --- | --- |
|
||||
| mistralai/Mistral-Small-3.2-24B-Instruct-2506 | Apache-2.0 | A ficha indica cerca de 55 GB GPU em BF16/FP16. Incompatível com a GPU virtual disponível. Quantização precisa de benchmark próprio. |
|
||||
| Qwen/Qwen3-4B-Instruct-2507 | Apache-2.0 | Estimativa aritmética de pesos: cerca de 8 GB a 16 bits ou 2 GB a 4 bits, antes de KV cache, runtime e metadados. Candidato menor para benchmark, não aprovado. |
|
||||
| BAAI/bge-m3 | MIT | Embeddings de 1024 dimensões, contexto máximo indicado de 8192 tokens; memória e latência locais não medidas. |
|
||||
| BAAI/bge-reranker-v2-m3 | Apache-2.0 | Cross-encoder multilingue; custo cresce com pares pergunta/fragmento. Medir antes de habilitar. |
|
||||
| pgvector 0.8.6 | PostgreSQL License | Código open source; extensão ausente no PostgreSQL local. Usar a mesma base, não uma base paralela. |
|
||||
| vLLM | Verificar licença/release do artefacto de implantação | Ambiente de inferência controlado por provisionar; não instalado nem validado nesta máquina. |
|
||||
| Ollama | Apenas protótipo local, conforme pedido | Não instalado. Não tratar o Windows virtual como equivalente ao hardware macOS anfitrião. |
|
||||
| Candidato fixado para avaliação | Licença declarada | Recursos e decisão |
|
||||
| --------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| mistralai/Mistral-Small-3.2-24B-Instruct-2506 | Apache-2.0 | A ficha indica cerca de 55 GB GPU em BF16/FP16. Incompatível com a GPU virtual disponível. Quantização precisa de benchmark próprio. |
|
||||
| Qwen/Qwen3-4B-Instruct-2507 | Apache-2.0 | Estimativa aritmética de pesos: cerca de 8 GB a 16 bits ou 2 GB a 4 bits, antes de KV cache, runtime e metadados. Candidato menor para benchmark, não aprovado. |
|
||||
| BAAI/bge-m3 | MIT | Embeddings de 1024 dimensões, contexto máximo indicado de 8192 tokens; memória e latência locais não medidas. |
|
||||
| BAAI/bge-reranker-v2-m3 | Apache-2.0 | Cross-encoder multilingue; custo cresce com pares pergunta/fragmento. Medir antes de habilitar. |
|
||||
| pgvector 0.8.6 | PostgreSQL License | Código open source; extensão ausente no PostgreSQL local. Usar a mesma base, não uma base paralela. |
|
||||
| vLLM | Verificar licença/release do artefacto de implantação | Ambiente de inferência controlado por provisionar; não instalado nem validado nesta máquina. |
|
||||
| Ollama | Apenas protótipo local, conforme pedido | Não instalado. Não tratar o Windows virtual como equivalente ao hardware macOS anfitrião. |
|
||||
|
||||
Estimativa de armazenamento vectorial bruto BGE-M3: 1024 × 4 bytes = 4096 bytes por fragmento; um milhão de fragmentos representa aproximadamente 4,1 GB decimais, sem índices, texto, WAL, backups e overhead. Planear esses adicionais por medição.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user