Artefactos

Próxima versión — Zylon 1.58Esta documentación se publica antes del lanzamiento para que puedas preparar tus integraciones de API. La imagen de la versión todavía no está disponible. Para instalaciones con 1.57, consulta la documentación de 1.57.

Un artefacto es una pieza de información (o un recurso listo para herramientas) que incorporas a Zylon para poder usarla como contexto en consultas y operaciones. Los artefactos viven dentro de una colección y cada uno tiene un ID artifact estable. Se pueden crear a partir de:

Tipo	Entrada	Notas
Text	Cadena	Contenido directo.
File	Bytes en base64	Para archivos como `.txt` o `.pdf`.
URI	URL	Zylon obtiene e ingesta el contenido.

Requisitos previos

Un token de API con el scope de escritura necesario. Consulta Backoffice Developer Console o Gestión de tokens.
El nombre de host de Zylon (sustituye {BASE_URL} en los ejemplos).

Todas las operaciones de artefactos de ZylonGPT, incluidas ingesta, listado, recuperación de contenido, estado de tareas y eliminación, requieren un scope de lectura y escritura. PrivateGPT.Read.All y Read.All con gateway_id devuelven 403 para todas las rutas de artefactos. Un token Read.All sin contexto de gateway no puede llamar a ZylonGPT.

Solicitud y respuesta básica

Usa POST /artifacts/ingest cuando quieras que la ingesta termine en la misma petición.

curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "{collectionID}",
    "artifact": "{artifactID}",
    "input": {
      "type": "text",
      "value": "Release notes: Shipped billing dashboard and fixed three bugs."
    },
    "metadata": {
      "file_name": "release_notes.txt",
      "source": "docs"
    }
  }'

Ejemplo de respuesta

{
  "object": "list",
  "model": "private-gpt",
  "data": [
    {
      "object": "ingest.document",
      "artifact": "docs_text_artifact_sync",
      "doc_metadata": {
        "file_name": "release_notes.txt"
      }
    }
  ]
}

Campos de respuesta de ingesta síncrona

Campo	Tipo	Significado
`object`, `model`	string	Tipo de respuesta y modelo.
`data`	object[]	Referencias de documentos ingeridos.
`data[].object`, `data[].artifact`	string	Tipo de documento e ID del artefacto.
`data[].doc_metadata`	object	Campos opcionales de tipo string que admiten null: `window`, `original_text`, `page_label`, `file_name`, `doc_id`.
`callback.properties`	JSON o null	Metadatos devueltos opcionales; es una clave literal del nivel superior, no un objeto anidado.

Los campos que admiten null pueden omitirse. La respuesta de ingesta síncrona no incluye metadatos arbitrarios del documento devueltos por el proveedor.

Ingesta asíncrona

Usa POST /artifacts/ingest/async para cuerpos de petición más grandes o cuando la ingesta pueda tardar. Envuelve el cuerpo de ingesta síncrona en ingest_body e incluye el objeto obligatorio callback. Usa callback: {} si consultas el estado sin configurar callbacks. La respuesta devuelve un task_id que puedes consultar.

Parametros del endpoint

Tipo	Nombre	Obligatorio	Notas
Body	`ingest_body`	Si	Cuerpo de ingesta síncrona con `collection`, `artifact` e `input` obligatorios; `metadata` opcional.
Body	`callback`	Si	Objeto de callback; se acepta `{}`. El campo opcional `properties` contiene datos de correlación.

Text
File
URI

curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_body": {
      "collection": "{collectionID}",
      "artifact": "{artifactID}",
      "input": {
        "type": "text",
        "value": "Release notes: We shipped a new billing dashboard and fixed three bugs."
      },
      "metadata": {
        "file_name": "release_notes.txt",
        "source": "docs"
      }
    },
    "callback": {}
  }'

curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_body": {
      "collection": "{collectionID}",
      "artifact": "{artifactID}",
      "input": {
        "type": "file",
        "value": "SGVsbG8gZnJvbSBmaWxlIGFydGlmYWN0Lgo="
      },
      "metadata": {
        "file_name": "onboarding_checklist.txt",
        "source": "docs"
      }
    },
    "callback": {}
  }'

curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "ingest_body": {
      "collection": "{collectionID}",
      "artifact": "{artifactID}",
      "input": {
        "type": "uri",
        "value": "https://example.com/"
      },
      "metadata": {
        "file_name": "example.html",
        "source": "docs"
      }
    },
    "callback": {}
  }'

Ejemplo de respuesta

{ "task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7" }

Consultar estado:

curl "https://{BASE_URL}/api/gpt/v1/artifacts/ingest/async/{task_id}" \
  -H "Authorization: Bearer {API_TOKEN}"

Ejemplo de respuesta

{
  "task_id": "f04e0709-131a-4a9d-b884-78872a4e63d7",
  "task_status": "PENDING",
  "task_result": null
}

Listar artefactos

curl "https://{BASE_URL}/api/gpt/v1/artifacts/list?collection={collectionID}" \
  -H "Authorization: Bearer {API_TOKEN}"

Ejemplo de respuesta

{
  "object": "list",
  "model": "private-gpt",
  "data": [
    {
      "object": "ingest.document",
      "artifact": "docs_file_artifact",
      "doc_metadata": {
        "file_name": "docs_file_artifact.txt",
        "artifact_id": "docs_file_artifact",
        "collection": "019c7569-f1f3-74da-8017-35d4a11f93ca"
      }
    }
  ]
}

Recuperar contenido

Contenido completo

curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/content" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "context_filter": {
      "collection": "{collectionID}"
    }
  }'

Ejemplo de respuesta

{
  "data": [
    {
      "artifact_id": "docs_file_artifact",
      "content": "Hello from file artifact.\n\n"
    }
  ]
}

Contenido en fragmentos

curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/chunked-content" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "context_filter": {
      "collection": "{collectionID}"
    },
    "max_tokens": 50
  }'

Ejemplo de respuesta

{
  "data": [
    {
      "artifact_id": "docs_file_artifact",
      "content": [
        { "type": "source", "sources": [{ "object": "context.chunk", "id": "c5f20f0f-56e6-44e0-99e8-0d4ff4bb87eb" }] },
        { "type": "text", "text": "**Context Information**:\nBelow is important information..." }
      ]
    }
  ]
}

Eliminar artefactos

Eliminar (síncrono):

curl -i -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/delete" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "{collectionID}",
    "artifact": "{artifactID}"
  }'

Ejemplo de respuesta

HTTP/2 200

null

Eliminar (asíncrono):

curl -X POST "https://{BASE_URL}/api/gpt/v1/artifacts/delete/async" \
  -H "Authorization: Bearer {API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "delete_body": {
      "collection": "{collectionID}",
      "artifact": "{artifactID}"
    }
  }'

Ejemplo de respuesta

{ "task_id": "2d48e74f-3eff-474e-b338-a931390ac218" }

Consultar estado:

curl "https://{BASE_URL}/api/gpt/v1/artifacts/delete/async/{task_id}" \
  -H "Authorization: Bearer {API_TOKEN}"

Ejemplo de respuesta

{
  "task_id": "2d48e74f-3eff-474e-b338-a931390ac218",
  "task_status": "PENDING",
  "task_result": null
}

Sigue consultando hasta que task_status sea "SUCCESS" o "FAILURE". Si falla mientras el índice se completa, reintenta luego.

Errores y casos límite

401/403: token ausente o permisos insuficientes.
404: colección o artefacto no encontrado.
409: tarea de ingesta/eliminación ya en progreso.
413: entrada demasiado grande para una ingesta.
422: cuerpo de la petición inválido.
Fallos asíncronos: cuando task_status es FAILURE, revisa task_result (por ejemplo routing_key_error: "ingest.failed" o delete.failed) y reintenta tras corregir la entrada.

Primeros pasos

Construye con Zylon

Coding Agents

Requisitos previos

Solicitud y respuesta básica

Ingesta asíncrona

Listar artefactos

Recuperar contenido

Contenido completo

Contenido en fragmentos

Eliminar artefactos

Errores y casos límite

​Requisitos previos

​Solicitud y respuesta básica

​Ingesta asíncrona

​Listar artefactos

​Recuperar contenido

​Contenido completo

​Contenido en fragmentos

​Eliminar artefactos

​Errores y casos límite

Requisitos previos

Solicitud y respuesta básica

Ingesta asíncrona

Listar artefactos

Recuperar contenido

Contenido completo

Contenido en fragmentos

Eliminar artefactos

Errores y casos límite