Extraer datos estructurados

Utiliza el recurso Extract cuando quieras que la API de MKA1 convierta un documento o imagen subido en un JSON estructurado. Puedes definir el esquema en línea para una solicitud puntual, o guardar primero una plantilla de esquema reutilizable.

Crear un esquema reutilizable

Guarda una plantilla de esquema cuando quieras ejecutar el mismo formato de extracción muchas veces.

mka1 llm extract create-schema \
  -H 'X-On-Behalf-Of: <end-user-id>' \
  --body '{
    "name": "Extracción de factura",
    "description": "Extraer los campos de cabecera de facturas PDF",
    "schema": {
      "type": "object",
      "properties": {
        "invoice_number": { "type": "string" },
        "vendor_name": { "type": "string" },
        "total_amount": { "type": "number" },
        "date": { "type": "string", "format": "date" }
      },
      "required": ["invoice_number", "total_amount"]
    },
    "metadata": { "document_type": "invoice" }
  }'

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

const mka1 = new SDK({
  apiKey: '<mka1-api-key>',
  headers: { 'X-On-Behalf-Of': '<end-user-id>' },
});

const schema = await mka1.llm.extract.createSchema({
  name: 'Extracción de factura',
  description: 'Extraer los campos de cabecera de facturas PDF',
  schema: {
    type: 'object',
    properties: {
      invoice_number: { type: 'string' },
      vendor_name: { type: 'string' },
      total_amount: { type: 'number' },
      date: { type: 'string', format: 'date' },
    },
    required: ['invoice_number', 'total_amount'],
  },
  metadata: {
    document_type: 'invoice',
  },
});

console.log(schema.id); // e.g. "schema_invoice_123"

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

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

// The Extract API is available at sdk.Llm.Extract
// Use sdk.Llm.Extract.CreateSchema(...) to save a reusable schema
// Refer to the API reference for the full method signature and types

from mka1 import SDK

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

schema = sdk.llm.extract.create_schema(
    name="Extracción de factura",
    description="Extraer los campos de cabecera de facturas PDF",
    schema={
        "type": "object",
        "properties": {
            "invoice_number": {"type": "string"},
            "vendor_name": {"type": "string"},
            "total_amount": {"type": "number"},
            "date": {"type": "string", "format": "date"},
        },
        "required": ["invoice_number", "total_amount"],
    },
)

print(schema.data.id)  # e.g. "schema_invoice_123"

curl https://apigw.mka1.com/api/v1/llm/extract/schema \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "name": "Extracción de factura",
    "description": "Extraer los campos de cabecera de facturas PDF",
    "schema": {
      "type": "object",
      "properties": {
        "invoice_number": {
          "type": "string"
        },
        "vendor_name": {
          "type": "string"
        },
        "total_amount": {
          "type": "number"
        },
        "date": {
          "type": "string",
          "format": "date"
        }
      },
      "required": [
        "invoice_number",
        "total_amount"
      ]
    },
    "metadata": {
      "document_type": "invoice"
    }
  }'

Esto devuelve un ID de esquema como schema_invoice_123.

Extraer con el esquema guardado

Utiliza el ID del esquema guardado para extraer datos de un archivo. La especificación OpenAPI admite multipart/form-data para esta solicitud.

mka1 llm extract extract-with-schema \
  --schema-id schema_invoice_123 \
  --model meetkai:functionary-es-mini \
  --prompt 'Extrae los campos estructurados de la factura.' \
  --file ./invoice.pdf

const file = Bun.file('./invoice.pdf');

const result = await mka1.llm.extract.extractWithSchema({
  schemaId: 'schema_invoice_123',
  extractWithSchemaRequestBody: {
    model: 'meetkai:functionary-es-mini',
    prompt: 'Extrae los campos estructurados de la factura.',
    file,
  },
});

console.log(result.data);

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

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var fileContent = await File.ReadAllBytesAsync("./invoice.pdf");

var result = await sdk.Llm.Extract.ExtractWithSchemaAsync(
    "schema_invoice_123",
    new ExtractWithSchemaRequestBody()
    {
        Model = "meetkai:functionary-es-mini",
        Prompt = "Extrae los campos estructurados de la factura.",
        File = new ExtractWithSchemaFile()
        {
            FileName = "invoice.pdf",
            Content = fileContent,
        },
    }
);

Console.WriteLine(result.ExtractionResponse?.Data);

result = sdk.llm.extract.extract_with_schema(
    schema_id="schema_invoice_123",
    model="meetkai:functionary-es-mini",
    file={
        "file_name": "invoice.pdf",
        "content": open("./invoice.pdf", "rb"),
    },
)

print(result.data)

curl https://apigw.mka1.com/api/v1/llm/extract/schema/schema_invoice_123 \
  --request POST \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --form 'model=meetkai:functionary-es-mini' \
  --form 'prompt=Extrae los campos estructurados de la factura.' \
  --form 'file=@./invoice.pdf'

Una respuesta exitosa devuelve un objeto JSON con:

success
data que contiene los campos extraídos
metadata sobre la ejecución de la extracción

Usar un esquema en línea para trabajos puntuales

Si no necesitas reutilizar el esquema, llama a POST /api/v1/llm/extract en su lugar. Proporciona tu JSON Schema en línea junto con los campos de la solicitud de extracción. Nota: en la especificación OpenAPI, este endpoint se define como application/json (el campo file se envía como una cadena codificada en binario).

mka1 llm extract extract \
  --model meetkai:functionary-es-mini \
  --prompt 'Extrae el número de factura y el total.' \
  --schema '{
    "type": "object",
    "properties": {
      "invoice_number": { "type": "string" },
      "total_amount": { "type": "number" }
    },
    "required": ["invoice_number", "total_amount"]
  }' \
  --file ./invoice.pdf

const file = Bun.file('./invoice.pdf');

const result = await mka1.llm.extract.extract({
  model: 'meetkai:functionary-es-mini',
  prompt: 'Extrae el número de factura y el total.',
  schema: {
    type: 'object',
    properties: {
      invoice_number: { type: 'string' },
      total_amount: { type: 'number' },
    },
    required: ['invoice_number', 'total_amount'],
  },
  file,
});

console.log(result.data);

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

var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

var fileContent = await File.ReadAllBytesAsync("./invoice.pdf");

var result = await sdk.Llm.Extract.ExtractAsync(new ExtractRequestBody()
{
    Model = "meetkai:functionary-es-mini",
    Prompt = "Extrae el número de factura y el total.",
    Schema = Newtonsoft.Json.JsonConvert.SerializeObject(new Dictionary<string, object>()
    {
        { "type", "object" },
        { "properties", new Dictionary<string, object>()
            {
                { "invoice_number", new Dictionary<string, object>() { { "type", "string" } } },
                { "total_amount", new Dictionary<string, object>() { { "type", "number" } } },
            }
        },
        { "required", new List<object>() { "invoice_number", "total_amount" } },
    }),
    File = new ExtractFile()
    {
        FileName = "invoice.pdf",
        Content = fileContent,
    },
});

Console.WriteLine(result.ExtractionResponse?.Data);

import json

result = sdk.llm.extract.extract(
    model="meetkai:functionary-es-mini",
    schema=json.dumps({
        "type": "object",
        "properties": {
            "invoice_number": {"type": "string"},
            "total_amount": {"type": "number"},
        },
        "required": ["invoice_number", "total_amount"],
    }),
    file={
        "file_name": "invoice.pdf",
        "content": open("./invoice.pdf", "rb"),
    },
)

print(result.data)

curl https://apigw.mka1.com/api/v1/llm/extract \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "model": "meetkai:functionary-es-mini",
    "prompt": "Extrae el número de factura y el total.",
    "schema": {
      "type": "object",
      "properties": {
        "invoice_number": {"type": "string"},
        "total_amount": {"type": "number"}
      },
      "required": ["invoice_number", "total_amount"]
    },
    "file": "(binary)"
  }'

Utiliza el flujo de esquemas reutilizables cuando quieras un contrato estable a través de muchos archivos.

Gestionar esquemas guardados

El recurso Extract también te permite:

Obtener un esquema guardado por ID.
Actualizar un esquema guardado.
Eliminar un esquema guardado.

Utiliza esos endpoints cuando tu contrato de extracción cambie con el tiempo y necesites mantener el esquema sincronizado.

​Crear un esquema reutilizable

​Extraer con el esquema guardado

​Usar un esquema en línea para trabajos puntuales

​Gestionar esquemas guardados

Crear un esquema reutilizable

Extraer con el esquema guardado

Usar un esquema en línea para trabajos puntuales

Gestionar esquemas guardados