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.

A API de Busca fornece duas maneiras de armazenar e recuperar textos:
  • Text Store — armazenamento vetorial pré-configurado com busca híbrida, desduplicação e agrupamento. Não é necessário configurar esquema ou índice.
  • Tables — acesso de baixo nível ao banco de dados vetorial com controle total sobre esquema, índices, filtros e operações de busca.
Comece com o Text Store para a maioria dos casos de uso. Use Tables quando precisar de esquemas personalizados, gerenciamento explícito de índices ou expressões de filtro avançadas. Se você precisa de um exemplo externo que mostre o GraphRAG superando a recuperação plana em um benchmark definido, veja Avaliação do GraphRAG.

​
Criar um text store

Forneça um nome e a dimensão do embedding para seus vetores. 
mka1 search text-store create \
  -H 'X-On-Behalf-Of: <end-user-id>' \
  --body '{
    "store_name": "product_catalog",
    "dimension": 3
  }'

​
Adicionar textos a um text store

Adicione textos com seus vetores de embedding pré-computados. Textos duplicados são automaticamente ignorados. O campo group marca as entradas para que você possa deletá-las ou recuperá-las como um conjunto posteriormente. 
mka1 search text-store add-texts \
  --store-name product_catalog \
  --body '{
    "texts": [
      "Noise-cancelling over-ear headphones with 30-hour battery.",
      "Compact wireless earbuds with active noise cancellation.",
      "Studio monitor headphones with flat frequency response."
    ],
    "vectors": [
      [0.16, -0.08, 0.29],
      [0.14, -0.06, 0.31],
      [0.09, -0.12, 0.22]
    ],
    "group": "headphones"
  }'

​
Buscar em um text store

Passe uma consulta de texto e seu vetor de embedding. O serviço executa uma busca híbrida combinando similaridade de texto completo e vetorial. 
mka1 search text-store search-texts \
  --store-name product_catalog \
  --body '{
    "query": "noise-cancelling headphones",
    "vector": [0.16, -0.08, 0.29],
    "limit": 5
  }'

​
Deletar texto de um text store

Remova entradas específicas pelos seus valores de texto exatos. 
mka1 search text-store delete-texts \
  --store-name product_catalog \
  --body '{
    "texts": [
      "Studio monitor headphones with flat frequency response."
    ]
  }'

​
Deletar textos por grupo de um text store

Remova todas as entradas que pertencem a um ou mais grupos. 
mka1 search text-store delete-texts \
  --store-name product_catalog \
  --body '{
    "groups": ["headphones"]
  }'

​
Deletar um text store

Remova o store e todos os seus dados. 
mka1 search text-store delete --store-name product_catalog

​
Uso Avançado: Tables

Tables fornecem acesso direto ao banco de dados vetorial subjacente. Você define o esquema, escolhe quais campos indexar, insere linhas estruturadas e compõe operações de busca manualmente.

​
Campos do esquema

Cada campo em um esquema de tabela possui um name, type e propriedades opcionais.
TipoDescriçãoSuporte a índice
stringDados de textoFTS (busca de texto completo)
intInteiro 32 bitsBTREE, BITMAP, LABEL_LIST
floatPonto flutuante 64 bitsBTREE, BITMAP, LABEL_LIST
datetimeTimestamp com fuso horário opcionalBTREE
vectorEmbedding de dimensão fixaIVF_FLAT, IVF_PQ, IVF_HNSW_PQ, IVF_HNSW_SQ
listLista de strings, ints ou floats—
Defina nullable como false para campos obrigatórios. Adicione "index": "FTS" em um campo string para habilitar busca de texto completo na criação. Campos vetoriais exigem a propriedade dimensions que deve corresponder ao tamanho do seu embedding.

​
Criar uma tabela de busca

Defina uma tabela com um esquema que descreva seus registros. O exemplo abaixo cria uma base de conhecimento de suporte com um campo de texto indexado para busca de texto completo e um campo vetorial para busca semântica. 
mka1 search tables create \
  --body '{
    "name": "support_kb",
    "schema": {
      "fields": [
        { "name": "id", "type": "string", "nullable": false },
        { "name": "content", "type": "string", "nullable": false, "index": "FTS" },
        { "name": "category", "type": "string", "nullable": false },
        { "name": "rating", "type": "float", "nullable": true },
        { "name": "embedding", "type": "vector", "nullable": false, "dimensions": 3 }
      ]
    }
  }'

​
Inserir linhas

Insira registros que correspondam ao esquema da tabela. Você pode enviar várias linhas em uma única requisição. 
mka1 search tables insert-data \
  --table-name support_kb \
  --body '{
    "data": [
      {
        "id": "doc_001",
        "content": "Reset your password from the account settings page.",
        "category": "account",
        "rating": 4.7,
        "embedding": [0.13, -0.09, 0.41]
      },
      {
        "id": "doc_002",
        "content": "Use two-factor authentication for added account security.",
        "category": "security",
        "rating": 4.9,
        "embedding": [0.07, -0.02, 0.36]
      }
    ]
  }'

​
Operações de busca

A busca em tabelas permite compor múltiplas operações em uma única requisição. As operações são executadas em ordem — comece com uma busca primária, depois refine com filtros, limites ou offsets. Operações primárias inicializam o conjunto de resultados:
OperaçãoDescrição
vector_searchEncontra linhas mais próximas de um vetor de consulta. Suporta tipos de distância cosine, l2, dot e hamming.
ftsBusca por palavra-chave em texto completo em um ou mais campos string.
Operações secundárias refinam os resultados:
OperaçãoDescrição
filterAplica uma expressão similar ao SQL. Defina prefilter como true para filtrar antes do ranqueamento.
limitLimita o número de linhas retornadas.
offsetPula as primeiras N linhas para paginação.
Use returnColumns para controlar quais campos retornam na resposta.

​
Buscar na tabela

O exemplo abaixo combina uma busca vetorial com um pré-filtro no campo category. 
mka1 search tables search-data \
  --table-name support_kb \
  --body '{
    "operations": [
      {
        "type": "vector_search",
        "field": "embedding",
        "vector": [0.11, -0.06, 0.37],
        "distanceType": "cosine",
        "limit": 5
      },
      {
        "type": "filter",
        "expression": "category = '\''security'\''",
        "prefilter": true
      }
    ],
    "returnColumns": ["id", "content", "category", "rating"]
  }'

​
Deletar linhas

Remova linhas de uma tabela usando uma expressão de filtro. 
mka1 search tables delete-data \
  --table-name support_kb \
  --body '{
    "filter": "id IN ('\''doc_001'\'', '\''doc_002'\'')"
  }'

​
Deletar uma tabela

Remova a tabela e todos os seus dados. 
mka1 search tables delete --table-name support_kb