Artefactos - Zylon

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. Ver Backoffice Developer Console.
El nombre de host de Zylon (sustituye {BASE_URL} en los ejemplos).

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",
        "source": "docs",
        "headers": [],
        "artifact_id": "docs_text_artifact_sync",
        "collection": "019c7569-f1f3-74da-8017-35d4a11f93ca",
        "llm_model": "default",
        "embed_model": "default",
        "hash": "faf6da679814136cb7cef94532397948cd2cd303b25f91a527af53227e9da99d"
      }
    }
  ]
}

Ingesta asíncrona

Usa POST /artifacts/ingest/async para cuerpos de petición más grandes o cuando la ingesta pueda tardar. El cuerpo es el mismo que en la ingesta síncrona, envuelto en ingest_body, y la respuesta devuelve un task_id que puedes consultar.

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"
      }
    }
  }'

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"
      }
    }
  }'

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"
      }
    }
  }'

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.

​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