OpenQCoreAI
Começar

Recursos · Knowledge API

Documentação da Knowledge API

Referência completa para ingestão e recuperação de conhecimento em workspaces, fluxos de consulta (ask) e restrições seguras para produção.

Voltar à documentaçãoIr para Endpoints

Endpoints

GET /api/v1/console/knowledge
POST /api/v1/console/knowledge
POST /api/v1/console/knowledge/upload
GET /api/v1/console/knowledge/{item_id}
PATCH /api/v1/console/knowledge/{item_id}
DELETE /api/v1/console/knowledge/{item_id}
POST /api/v1/console/knowledge/ask

Cabeçalhos obrigatórios

Authorization: Bearer [token] ou autenticação por API keyX-Scope-Type: workspaceX-Workspace-ID: [workspace_uuid]Content-Type: application/json (ou multipart/form-data para upload)

Exemplo de upload

bash
curl -X POST "/api/v1/console/knowledge/upload" \
  -H "Authorization: Bearer [token]" \
  -H "X-Scope-Type: workspace" \
  -H "X-Workspace-ID: [workspace_uuid]" \
  -F "file=@handbook.pdf" \
  -F "title=Team Handbook" \
  -F "tags=hr,policy"

Exemplo de consulta

json
{
  "question": "What is our remote-work policy?",
  "top_k": 5,
  "filters": {
    "tags": ["hr", "policy"]
  },
  "session_id": "sess_123"
}

Exemplo de resposta

json
{
  "success": true,
  "answer": "Employees may work remotely up to 3 days per week...",
  "citations": [
    {
      "item_id": "kb_456",
      "title": "Team Handbook",
      "score": 0.91
    }
  ],
  "usage": {
    "input_tokens": 180,
    "output_tokens": 72
  },
  "metadata": {
    "retrieved_items": 5
  }
}

Restrições de conhecimento

  • Tamanho máximo de ficheiro: 20 MB por upload.
  • Formatos suportados: PDF, DOC, DOCX, TXT, Markdown.
  • A ingestão é executada de forma assíncrona por processos em segundo plano.
  • As operações de conhecimento no console exigem o escopo do workspace.

Ciclo de vida da ingestão

  1. pendente: ficheiro aceite e enfileirado.
  2. a processar: extração, segmentação e geração de embeddings em curso.
  3. processado: item indexado e pronto para consulta.
  4. falhou: a ingestão falhou e gerou metadados de diagnóstico.

Modelos de erro

400

Payload inválido ou filtros malformados.

401

Autenticação ausente ou inválida.

403

Acesso ao workspace negado por função/âmbito.

404

Item de conhecimento não encontrado.

413

Ficheiro enviado excede o tamanho permitido.

415

Tipo de conteúdo do ficheiro não suportado.

422

Falha de validação no esquema/contexto da requisição.

429

Limite de requisições excedido.