Usar arquivos e armazenamentos de vetores

Use Arquivos para enviar documentos uma vez. Use Armazenamentos de Vetores para indexar esses arquivos para busca e recuperação semânticas. Este é o padrão padrão para assistentes baseados em documentos, fluxos de recuperação e respostas fundamentadas.

Fazer upload de um arquivo

Faça upload do arquivo com multipart/form-data. A especificação OpenAPI ativa exige file e purpose.

mka1 llm files upload \
  --file ./support-manual.pdf \
  --purpose assistants \
  -H 'X-On-Behalf-Of: <end-user-id>'

import { SDK } from '@meetkai/mka1';

const mka1 = new SDK({ bearerAuth: 'Bearer <mka1-api-key>' });

const file = Bun.file('./support-manual.pdf');
const result = await mka1.llm.files.upload({
  xOnBehalfOf: '<end-user-id>', // opcional — atribua a solicitação a um dos seus usuários finais
  requestBody: { file, purpose: 'assistants' },
});

import OpenAI from 'openai';
import fs from 'fs';

const openai = new OpenAI({
  apiKey: '<mka1-api-key>',
  baseURL: 'https://apigw.mka1.com/api/v1/llm',
  defaultHeaders: { 'X-On-Behalf-Of': '<end-user-id>' },
});

const file = await openai.files.create({
  file: fs.createReadStream('./support-manual.pdf'),
  purpose: 'assistants',
});

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using MeetKai.MKA1.Types.Requests;

var sdk = new SDK(
    bearerAuth: $"Bearer {YOUR_API_KEY}",
    serverUrl: "https://apigw.mka1.com"
);

var res = await sdk.Llm.Files.UploadAsync(new UploadFileRequestBody()
{
    File = new UploadFileFile()
    {
        FileName = "support-manual.pdf",
        Content = System.IO.File.ReadAllBytes("./support-manual.pdf"),
    },
    Purpose = UploadFilePurpose.Assistants,
});

from meetkai_mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

result = sdk.llm.files.upload(
    file={
        "file_name": "support-manual.pdf",
        "content": open("./support-manual.pdf", "rb"),
    },
    purpose="assistants",
)

curl https://apigw.mka1.com/api/v1/llm/files \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --form 'file=@./support-manual.pdf' \
  --form 'purpose=assistants'

A resposta retorna um objeto file com um ID como file-abc123.

Criar um armazenamento de vetores

Crie um armazenamento de vetores e anexe um ou mais IDs de arquivos enviados.

mka1 llm vector-stores create --body '{
  "name": "Base de conhecimento de suporte",
  "description": "Manuais de suporte e documentos da central de ajuda indexados",
  "file_ids": ["file-abc123"],
  "expires_after": { "anchor": "last_active_at", "days": 30 }
}'

const vectorStore = await mka1.llm.vectorStores.create({
  xOnBehalfOf: '<end-user-id>',
  createVectorStoreRequest: {
    name: 'Base de conhecimento de suporte',
    description: 'Manuais de suporte e documentos da central de ajuda indexados',
    fileIds: ['file-abc123'],
    expiresAfter: { anchor: 'last_active_at', days: 30 },
  },
});

const vectorStore = await openai.vectorStores.create({
  name: 'Base de conhecimento de suporte',
  description: 'Manuais de suporte e documentos da central de ajuda indexados',
  file_ids: ['file-abc123'],
  expires_after: { anchor: 'last_active_at', days: 30 },
});

var vs = await sdk.Llm.VectorStores.CreateAsync(new CreateVectorStoreRequest()
{
    Name = "Base de conhecimento de suporte",
    Description = "Manuais de suporte e documentos da central de ajuda indexados",
});

vector_store = sdk.llm.vector_stores.create(
    name="Base de conhecimento de suporte",
    description="Manuais de suporte e documentos da central de ajuda indexados",
)

curl https://apigw.mka1.com/api/v1/llm/vector_stores \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "Base de conhecimento de suporte",
    "description": "Manuais de suporte e documentos da central de ajuda indexados",
    "file_ids": [
      "file-abc123"
    ],
    "expires_after": {
      "anchor": "last_active_at",
      "days": 30
    }
  }'

Esta resposta retorna um ID de armazenamento de vetores como vs_abc123.

Criar um armazenamento de grafo

Defina retrieval_mode como "graph" para obter recuperação com reconhecimento de grafo em vez de similaridade vetorial simples. Em um armazenamento de grafo, entidades e relações são extraídas de cada trecho na ingestão para construir um grafo de conhecimento, e a busca percorre esse grafo para coletar evidências conectadas, em vez de retornar apenas os trechos mais próximos. Os ganhos aparecem em perguntas que exigem ligar fatos entre vários documentos. Duas opções se aplicam somente a armazenamentos de grafo:

extraction_model — o modelo usado para extração de entidades e relações. Segue o mesmo contrato de embedding_model: opcional, tem auto como padrão e é resolvido para um modelo concreto na criação.
max_hops — até onde expandir pelo grafo em cada consulta, de 1 a 4. O padrão é 2.

mka1 llm vector-stores create --body '{
  "name": "Grafo de conhecimento de suporte",
  "description": "Manuais de suporte indexados para recuperação multi-hop",
  "file_ids": ["file-abc123"],
  "retrieval_mode": "graph",
  "extraction_model": "auto",
  "max_hops": 2
}'

const graphStore = await mka1.llm.vectorStores.create({
  xOnBehalfOf: '<end-user-id>',
  createVectorStoreRequest: {
    name: 'Grafo de conhecimento de suporte',
    description: 'Manuais de suporte indexados para recuperação multi-hop',
    fileIds: ['file-abc123'],
    retrievalMode: 'graph',
    extractionModel: 'auto',
    maxHops: 2,
  },
});

// Armazenamentos de grafo são criados pelo método VectorStores.Create, com os
// parâmetros RetrievalMode, ExtractionModel e MaxHops.
// Consulte a referência da API para a assinatura completa do método.

graph_store = sdk.llm.vector_stores.create(
    name="Grafo de conhecimento de suporte",
    description="Manuais de suporte indexados para recuperação multi-hop",
    file_ids=["file-abc123"],
    retrieval_mode="graph",
    extraction_model="auto",
    max_hops=2,
)

curl https://apigw.mka1.com/api/v1/llm/vector_stores \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "name": "Grafo de conhecimento de suporte",
    "description": "Manuais de suporte indexados para recuperação multi-hop",
    "file_ids": [
      "file-abc123"
    ],
    "retrieval_mode": "graph",
    "extraction_model": "auto",
    "max_hops": 2
  }'

A resposta devolve retrieval_mode, extraction_model e max_hops, com extraction_model já resolvido para o modelo concreto, e não como auto. Você pesquisa um armazenamento de grafo com a mesma chamada de busca usada em qualquer outro armazenamento de vetores — o modo é uma propriedade do armazenamento, não da requisição.

O que muda em um armazenamento de grafo

O modo é congelado na criação. Não há como converter um armazenamento entre vector e graph depois; o endpoint de atualização não aceita retrieval_mode. Trocar significa criar um novo armazenamento e reanexar os arquivos.
A extração é medida no seu consumo. Entidades e relações são extraídas de cada trecho na ingestão, e cada consulta também executa uma passagem de extração para identificar as entidades a partir das quais expandir. Ambas são cobradas como uso normal de modelo, então um armazenamento de grafo custa mais para preencher e mais para consultar do que um armazenamento de vetores sobre os mesmos arquivos.
A busca em grafo retorna no máximo 20 resultados. max_num_results aceita até 50, mas consultas em grafo são limitadas a 20. Um valor maior é truncado, não rejeitado.
Filtros por atributo podem devolver menos resultados. Como observado em Filtrar a busca por atributos de arquivo, a filtragem em um armazenamento de grafo é aplicada parcialmente após a recuperação, portanto uma busca filtrada pode retornar menos correspondências do que max_num_results.
extraction_model e max_hops são exclusivos de grafo. Enviar qualquer um deles sem retrieval_mode: "graph" retorna 400.

Adicionar mais arquivos depois

Você pode adicionar mais arquivos a um armazenamento de vetores existente sem recriá-lo.

mka1 llm vector-stores create-file \
  --vector-store-id vs_abc123 \
  --file-id file-def456 \
  --attributes '{"category":"manual","version":"2.0"}'

const vsFile = await mka1.llm.vectorStores.createFile({
  vectorStoreId: 'vs_abc123',
  xOnBehalfOf: '<end-user-id>',
  createVectorStoreFileRequest: {
    fileId: 'file-def456',
    attributes: { category: 'manual', version: '2.0' },
  },
});

const vsFile = await openai.vectorStores.files.create('vs_abc123', {
  file_id: 'file-def456',
});

// A adição de arquivos a um armazenamento de vetores existente é feita por meio dos
// métodos de API VectorStores.CreateFile ou VectorStores.Files.
// Consulte a referência da API para ver a assinatura completa do método.

vs_file = sdk.llm.vector_stores.create_file(
    vector_store_id="vs_abc123",
    file_id="file-def456",
)

curl https://apigw.mka1.com/api/v1/llm/vector_stores/vs_abc123/files \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "file_id": "file-def456",
    "attributes": {
      "category": "manual",
      "version": "2.0"
    }
  }'

O arquivo do armazenamento de vetores pode retornar status: "in_progress" enquanto a indexação é executada. Um arquivo só fica pesquisável quando o status chega a "completed" — uma busca feita antes disso tem sucesso, mas omite o arquivo, então consulte o status até "completed" em vez de assumir uma espera fixa. A indexação normalmente termina em segundos, mas a latência varia conforme o tamanho do arquivo e a carga. Consulte os endpoints de Arquivos e Armazenamentos de Vetores na Referência da API para o endpoint de consulta de status.

Listar arquivos com paginação

As listagens de arquivos são ordenadas por created_at (os mais recentes primeiro por padrão) e retornam até limit itens por página. Quando has_more for true, passe o id do último item como after para buscar a próxima página.

mka1 llm vector-stores list-files \
  --vector-store-id vs_abc123 \
  --limit 5 \
  --after file-def456

let after: string | undefined;
do {
  const page = await mka1.llm.vectorStores.listFiles({
    vectorStoreId: 'vs_abc123',
    limit: 5,
    after,
    xOnBehalfOf: '<end-user-id>',
  });
  for (const vsFile of page.data) {
    console.log(vsFile.id);
  }
  after = page.hasMore ? page.lastId : undefined;
} while (after);

// O SDK da OpenAI pagina automaticamente: itere e ele seguirá o cursor para você.
for await (const vsFile of openai.vectorStores.files.list('vs_abc123', {
  limit: 5,
})) {
  console.log(vsFile.id);
}

// A listagem está disponível pelo método VectorStores.ListFiles; passe o id
// do último item como `after` enquanto `has_more` for verdadeiro.
// Consulte a referência da API para ver a assinatura completa do método.

after = None
while True:
    page = sdk.llm.vector_stores.list_files(
        vector_store_id="vs_abc123",
        limit=5,
        after=after,
    )
    for vs_file in page.data:
        print(vs_file.id)
    if not page.has_more:
        break
    after = page.last_id

curl "https://apigw.mka1.com/api/v1/llm/vector_stores/vs_abc123/files?limit=5&after=file-def456" \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'

Para paginar para trás, passe o id de um item como before: a resposta será a página imediatamente anterior a esse item na ordem de exibição. Arquivos anexados no mesmo lote podem compartilhar um carimbo de data e hora de criação; o cursor considera isso, portanto, uma varredura completa retorna cada arquivo exatamente uma vez. Se o arquivo de um cursor não existir mais — por exemplo, se ele foi removido do armazenamento de vetores enquanto você paginava — a API retorna 400 Invalid pagination cursor. Reinicie a varredura a partir da primeira página.

Pesquisar no armazenamento de vetores

Use a busca semântica para recuperar os blocos mais relevantes para uma pergunta do usuário.

mka1 llm vector-stores search \
  --vector-store-id vs_abc123 \
  --body '{
    "query": "Como faço para redefinir minha senha?",
    "max_num_results": 5
  }'

const results = await mka1.llm.vectorStores.search({
  vectorStoreId: 'vs_abc123',
  xOnBehalfOf: '<end-user-id>',
  searchVectorStoreRequest: {
    query: 'Como faço para redefinir minha senha?',
    maxNumResults: 5,
  },
});

const results = await openai.vectorStores.search('vs_abc123', {
  query: 'Como faço para redefinir minha senha?',
  max_num_results: 5,
});

// A busca está disponível pelo método VectorStores.Search.
// Consulte a referência da API para ver a assinatura completa do método.

results = sdk.llm.vector_stores.search(
    vector_store_id="vs_abc123",
    query="Como faço para redefinir minha senha?",
)

curl https://apigw.mka1.com/api/v1/llm/vector_stores/vs_abc123/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "query": "Como faço para redefinir minha senha?",
    "max_num_results": 5
  }'

A resposta retorna correspondências classificadas com file_id, filename, dados de pontuação, conteúdo dos blocos e os attributes atuais do arquivo.

Filtrar a busca por atributos de arquivo

Os atributos são metadados de chave-valor no nível do arquivo — valores de string, número ou booleanos — definidos quando você anexa um arquivo (consulte Adicionar mais arquivos depois). Você pode alterá-los após a ingestão com o endpoint update-file (POST /vector_stores/{vector_store_id}/files/{file_id}); a busca sempre avalia os valores atuais. Passe filters na solicitação de busca para restringir os resultados a arquivos cujos atributos correspondam. Um filtro é uma comparação — eq, ne, gt, gte, lt, lte, in, nin — ou um composto and/or de filtros aninhados.

mka1 llm vector-stores search \
  --vector-store-id vs_abc123 \
  --body '{
    "query": "Como faço para redefinir minha senha?",
    "max_num_results": 5,
    "filters": {
      "type": "and",
      "filters": [
        { "type": "eq", "key": "category", "value": "manual" },
        { "type": "ne", "key": "version", "value": "1.0" }
      ]
    }
  }'

const results = await mka1.llm.vectorStores.search({
  vectorStoreId: 'vs_abc123',
  xOnBehalfOf: '<end-user-id>',
  searchVectorStoreRequest: {
    query: 'Como faço para redefinir minha senha?',
    maxNumResults: 5,
    filters: {
      type: 'and',
      filters: [
        { type: 'eq', key: 'category', value: 'manual' },
        { type: 'ne', key: 'version', value: '1.0' },
      ],
    },
  },
});

const results = await openai.vectorStores.search('vs_abc123', {
  query: 'Como faço para redefinir minha senha?',
  max_num_results: 5,
  filters: {
    type: 'and',
    filters: [
      { type: 'eq', key: 'category', value: 'manual' },
      { type: 'ne', key: 'version', value: '1.0' },
    ],
  },
});

// A busca filtrada está disponível pelo parâmetro Filters do método
// VectorStores.Search (ComparisonFilter / CompoundFilter).
// Consulte a referência da API para ver a assinatura completa do método.

results = sdk.llm.vector_stores.search(
    vector_store_id="vs_abc123",
    query="Como faço para redefinir minha senha?",
    filters={
        "type": "and",
        "filters": [
            {"type": "eq", "key": "category", "value": "manual"},
            {"type": "ne", "key": "version", "value": "1.0"},
        ],
    },
)

curl https://apigw.mka1.com/api/v1/llm/vector_stores/vs_abc123/search \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "query": "Como faço para redefinir minha senha?",
    "max_num_results": 5,
    "filters": {
      "type": "and",
      "filters": [
        { "type": "eq", "key": "category", "value": "manual" },
        { "type": "ne", "key": "version", "value": "1.0" }
      ]
    }
  }'

A avaliação de filtros segue estas regras:

Um arquivo que não possui a key do filtro nunca corresponde — inclusive para ne e nin. Um filtro só inclui um arquivo com base em evidências, nunca por ausência.
eq e ne usam igualdade estrita, sem coerção de tipo: a string "2" não é igual ao número 2.
gt, gte, lt e lte comparam apenas números; um atributo ou valor de filtro não numérico falha na comparação.
in e nin recebem um value de matriz e verificam se o atributo do arquivo é (ou não é) um de seus elementos.
Os compostos and e or podem ser aninhados em qualquer profundidade.
Em armazenamentos de grafo, a filtragem é aplicada após a recuperação, portanto, uma busca filtrada pode retornar menos correspondências do que max_num_results.

Fluxo de trabalho típico

Use esta sequência para a maioria das configurações de recuperação:

Faça upload do arquivo de origem.
Crie um armazenamento de vetores com file_ids ou anexe o arquivo depois.
Aguarde a conclusão do processamento do arquivo.
Pesquise no armazenamento de vetores quando precisar de contexto relevante.

Depois, você pode inserir o texto retornado na lógica da sua própria aplicação ou em uma solicitação Responses.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Usar arquivos e armazenamentos de vetores

Fazer upload de um arquivo

Criar um armazenamento de vetores

Criar um armazenamento de grafo

O que muda em um armazenamento de grafo

Adicionar mais arquivos depois

Listar arquivos com paginação

Pesquisar no armazenamento de vetores

Filtrar a busca por atributos de arquivo

Fluxo de trabalho típico

​Fazer upload de um arquivo

​Criar um armazenamento de vetores

​Criar um armazenamento de grafo

​O que muda em um armazenamento de grafo

​Adicionar mais arquivos depois

​Listar arquivos com paginação

​Pesquisar no armazenamento de vetores

​Filtrar a busca por atributos de arquivo

​Fluxo de trabalho típico

Fazer upload de um arquivo

Criar um armazenamento de vetores

Criar um armazenamento de grafo

O que muda em um armazenamento de grafo

Adicionar mais arquivos depois

Listar arquivos com paginação

Pesquisar no armazenamento de vetores

Filtrar a busca por atributos de arquivo

Fluxo de trabalho típico