Usar archivos y almacenes vectoriales

Usa Archivos para subir documentos una sola vez. Usa Almacenes Vectoriales para indexar esos archivos y realizar búsquedas semánticas y recuperación de información. Este es el patrón estándar para asistentes respaldados por documentos, flujos de trabajo de recuperación y respuestas fundamentadas.

Subir un archivo

Sube el archivo usando multipart/form-data. La especificación OpenAPI en vivo requiere file y 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 — atribuye la solicitud a uno de tus usuarios finales
  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'

La respuesta devuelve un objeto file con un ID como file-abc123.

Crear un almacén vectorial

Crea un almacén vectorial y adjunta uno o más IDs de archivos subidos.

mka1 llm vector-stores create --body '{
  "name": "Base de conocimientos de soporte",
  "description": "Manuales de soporte y documentos del centro de ayuda 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 conocimientos de soporte',
    description: 'Manuales de soporte y documentos del centro de ayuda indexados',
    fileIds: ['file-abc123'],
    expiresAfter: { anchor: 'last_active_at', days: 30 },
  },
});

const vectorStore = await openai.vectorStores.create({
  name: 'Base de conocimientos de soporte',
  description: 'Manuales de soporte y documentos del centro de ayuda 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 conocimientos de soporte",
    Description = "Manuales de soporte y documentos del centro de ayuda indexados",
});

vector_store = sdk.llm.vector_stores.create(
    name="Base de conocimientos de soporte",
    description="Manuales de soporte y documentos del centro de ayuda 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 conocimientos de soporte",
    "description": "Manuales de soporte y documentos del centro de ayuda indexados",
    "file_ids": [
      "file-abc123"
    ],
    "expires_after": {
      "anchor": "last_active_at",
      "days": 30
    }
  }'

Esta respuesta devuelve un ID de almacén vectorial como vs_abc123.

Crear un almacén de grafos

Establece retrieval_mode en "graph" para obtener recuperación consciente de grafos en lugar de similitud vectorial simple. En un almacén de grafos, las entidades y relaciones se extraen de cada fragmento durante la ingesta para construir un grafo de conocimiento, y la búsqueda recorre ese grafo para reunir evidencia conectada en lugar de devolver únicamente los fragmentos más cercanos. Las mejoras aparecen en preguntas que requieren enlazar hechos entre varios documentos. Dos opciones se aplican solo a los almacenes de grafos:

extraction_model — el modelo usado para la extracción de entidades y relaciones. Sigue el mismo contrato que embedding_model: opcional, su valor predeterminado es auto y se resuelve a un modelo concreto en el momento de la creación.
max_hops — hasta dónde expandirse por el grafo en cada consulta, de 1 a 4. El valor predeterminado es 2.

mka1 llm vector-stores create --body '{
  "name": "Grafo de conocimiento de soporte",
  "description": "Manuales de soporte indexados para recuperación multi-salto",
  "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 conocimiento de soporte',
    description: 'Manuales de soporte indexados para recuperación multi-salto',
    fileIds: ['file-abc123'],
    retrievalMode: 'graph',
    extractionModel: 'auto',
    maxHops: 2,
  },
});

// Los almacenes de grafos se crean con el método VectorStores.Create, mediante
// los parámetros RetrievalMode, ExtractionModel y MaxHops.
// Consulta la referencia de la API para ver la firma completa del método.

graph_store = sdk.llm.vector_stores.create(
    name="Grafo de conocimiento de soporte",
    description="Manuales de soporte indexados para recuperación multi-salto",
    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 conocimiento de soporte",
    "description": "Manuales de soporte indexados para recuperación multi-salto",
    "file_ids": [
      "file-abc123"
    ],
    "retrieval_mode": "graph",
    "extraction_model": "auto",
    "max_hops": 2
  }'

La respuesta devuelve retrieval_mode, extraction_model y max_hops, con extraction_model ya resuelto al modelo concreto en lugar de auto. Un almacén de grafos se consulta con la misma llamada de búsqueda que cualquier otro almacén vectorial: el modo es una propiedad del almacén, no de la solicitud.

Qué cambia en un almacén de grafos

El modo queda fijado en la creación. No hay forma de convertir un almacén entre vector y graph después; el endpoint de actualización no acepta retrieval_mode. Cambiarlo implica crear un almacén nuevo y volver a adjuntar los archivos.
La extracción se contabiliza en tu consumo. Las entidades y relaciones se extraen de cada fragmento durante la ingesta, y cada consulta ejecuta además una pasada de extracción para identificar las entidades desde las que expandirse. Ambas se facturan como uso normal de modelo, así que un almacén de grafos cuesta más de llenar y más de consultar que un almacén vectorial sobre los mismos archivos.
La búsqueda en grafo devuelve como máximo 20 resultados. max_num_results admite hasta 50, pero las consultas en grafo se limitan a 20. Un valor mayor se trunca, no se rechaza.
extraction_model y max_hops son exclusivos de grafo. Enviar cualquiera de los dos sin retrieval_mode: "graph" devuelve 400.

Agregar más archivos después

Puedes agregar más archivos a un almacén vectorial existente sin tener que recrearlo.

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({
  xOnBehalfOf: '<end-user-id>',
  vectorStoreId: 'vs_abc123',
  createVectorStoreFileRequest: {
    fileId: 'file-def456',
    attributes: { category: 'manual', version: '2.0' },
  },
});

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

// Agregar archivos a un almacén vectorial existente se realiza mediante los métodos
// VectorStores.CreateFile o VectorStores.Files de la API.
// Consulta la referencia de la API para ver la firma completa del 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"
    }
  }'

El archivo del almacén vectorial puede devolver status: "in_progress" mientras se realiza la indexación. Un archivo no se puede buscar hasta que su estado llega a "completed": una búsqueda anterior a ese momento tiene éxito, pero omite el archivo, así que consulta el estado hasta "completed" en lugar de asumir una espera fija. La indexación suele terminar en segundos, pero la latencia varía según el tamaño del archivo y la carga. Consulta los endpoints de Archivos y Almacenes Vectoriales en la Referencia de la API para el endpoint de consulta de estado.

Buscar en el almacén vectorial

Usa la búsqueda semántica para recuperar los fragmentos más relevantes para una pregunta de usuario.

mka1 llm vector-stores search \
  --vector-store-id vs_abc123 \
  --body '{
    "query": "¿Cómo restablezco mi contraseña?",
    "max_num_results": 5
  }'

const results = await mka1.llm.vectorStores.search({
  xOnBehalfOf: '<end-user-id>',
  vectorStoreId: 'vs_abc123',
  searchVectorStoreRequest: {
    query: '¿Cómo restablezco mi contraseña?',
    maxNumResults: 5,
  },
});

const results = await openai.vectorStores.search('vs_abc123', {
  query: '¿Cómo restablezco mi contraseña?',
  max_num_results: 5,
});

// La búsqueda está disponible mediante el método VectorStores.Search.
// Consulta la referencia de la API para ver la firma completa del método.

results = sdk.llm.vector_stores.search(
    vector_store_id="vs_abc123",
    query="¿Cómo restablezco mi contraseña?",
)

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": "¿Cómo restablezco mi contraseña?",
    "max_num_results": 5
  }'

La respuesta devuelve coincidencias ordenadas con file_id, filename, datos de puntuación y el contenido del fragmento.

Flujo de trabajo típico

Utiliza esta secuencia para la mayoría de configuraciones de recuperación:

Sube el archivo fuente.
Crea un almacén vectorial con file_ids, o adjunta el archivo más tarde.
Espera a que se complete el procesamiento del archivo.
Busca en el almacén vectorial cuando necesites contexto relevante.

Luego puedes utilizar el texto devuelto en la lógica de tu propia aplicación o en una solicitud de Respuestas.

Comenzar

Respuestas

Funciones

Compute

CLI

Recetas

Comparativas

Infraestructura

Usar archivos y almacenes vectoriales

Subir un archivo

Crear un almacén vectorial

Crear un almacén de grafos

Qué cambia en un almacén de grafos

Agregar más archivos después

Buscar en el almacén vectorial

Flujo de trabajo típico

​Subir un archivo

​Crear un almacén vectorial

​Crear un almacén de grafos

​Qué cambia en un almacén de grafos

​Agregar más archivos después

​Buscar en el almacén vectorial

​Flujo de trabajo típico

Subir un archivo

Crear un almacén vectorial

Crear un almacén de grafos

Qué cambia en un almacén de grafos

Agregar más archivos después

Buscar en el almacén vectorial

Flujo de trabajo típico