Saltar al contenido principal

​
Cómo funciona

Cuando añades la herramienta de búsqueda semántica y el contexto especificado a tu solicitud de API, Zylon sigue estos pasos:
  1. Determina consultas: Zylon analiza tu pregunta y determina qué consulta o consultas específicas debe realizar para buscar en los documentos seleccionados.
  2. Realiza búsquedas semánticas: Ejecuta búsquedas usando la herramienta contra la base de conocimiento ingerida.
  3. Analiza y responde: Analiza todas las respuestas obtenidas y devuelve una respuesta coherente con citas opcionales de las fuentes encontradas.

​
Notas importantes

  • Para usar esta herramienta, debes especificar el tipo semantic_search_v1.
  • El tool_context debe contener al menos un artefacto de tipo ingested_artifact.
  • Los artefactos deben haber sido previamente ingeridos en el sistema.

​
Ejemplo de uso

En este ejemplo práctico, subimos un documento financiero de Apple y luego realizamos consultas semánticas sobre su contenido.
1

Subir el documento

Primero, ingerimos el documento que queremos consultar en nuestro sistema. En este caso, usamos el informe financiero Q2 FY25 de Apple.
curl --location 'https://<your-host>/api/gpt/v1/artifacts/ingest' \
--header 'Authorization: Bearer <your-token>' \
--header 'x-org: default' \
--header 'Content-Type: application/json' \
--data '{
  "artifact": "cefdf840-c0cb-4ff5-98ac-897e79f4c68b",
  "input": {
    "value": "https://www.apple.com/newsroom/pdfs/fy2025-q2/FY25_Q2_Consolidated_Financial_Statements.pdf",
    "type": "uri"
  },
  "collection": "stock_documents"
}'
2

Realizar búsqueda semántica

Una vez que el documento está procesado, realizamos la consulta especificando mensajes, herramientas, contexto y elección de herramienta en el cuerpo de la solicitud.
curl --location 'https://<your-host>/api/gpt/v1/messages' \
--header 'Authorization: Bearer <your-token>' \
--header 'x-org: default' \
--header 'Content-Type: application/json' \
--data '{
  "messages": [
    {
      "role": "user",
      "content": "Total net sales in March 2025 and March 2024?"
    }
  ],
  "tools": [
    {
      "name": "semantic_search",
      "type": "semantic_search_v1"
    }
  ],
  "tool_choice": { "type": "auto" },
  "tool_context": [
    {
      "type": "ingested_artifact",
      "context_filter": {
        "collection": "stock_documents",
        "artifacts": [
          "cefdf840-c0cb-4ff5-98ac-897e79f4c68b"
        ]
      }
    }
  ]
}'
3

Respuesta

El sistema responde con las búsquedas realizadas, los resultados encontrados y la respuesta final:
 {
   "id": "msg_1b3644e55d0d4f2da6397fd198a22869",
   "type": "message",
   "role": "assistant",
   "content": [
       {
           "type": "tool_use",
           "start_timestamp": "2025-09-24T11:34:06.309697Z",
           "stop_timestamp": "2025-09-24T11:34:09.614997Z",
           "id": "toolu_01997b808ce57f979564f1bb01efa316",
           "name": "semantic_search",
           "input": {
               "query": "Total net sales in March 2025"
           }
       },
       {
           "type": "tool_result",
           "start_timestamp": "2025-09-24T11:34:10.684899Z",
           "stop_timestamp": "2025-09-24T11:34:10.688481Z",
           "tool_use_id": "toolu_01997b808ce57f979564f1bb01efa316",
           "content": [
               {
                   "type": "source",
                   "sources": [
                       {
                           "object": "context.chunk",
                           "id": "9d7ba0b0-6bfb-4a9a-8f3a-a18ba3ae7330",
                           "score": 0.6927993893623352,
                           "document": {
                               "object": "ingest.document",
                               "artifact": "cefdf840-c0cb-4ff5-98ac-897e79f4c68b",
                               "doc_metadata": {
                                   "file_name": "FY25_Q2_Consolidated_Financial_Statements.pdf",
                                   "artifact_id": "cefdf840-c0cb-4ff5-98ac-897e79f4c68b",
                                   "collection": "stock_documents"
                               }
                           },
                           "text": "## CONDENSED CONSOLIDATED ...",
                           "content_type": "text/markdown",
                           "previous_texts": [],
                           "next_texts": [],
                           "metadata": {
                               "page": 1,
                               "shorter_id": "J7SS",
                               "abs_idx": 43,
                               "rel_idx": 0,
                               "file_name": "FY25_Q2_Consolidated_Financial_Statements.pdf",
                               "artifact_id": "cefdf840-c0cb-4ff5-98ac-897e79f4c68b",
                               "collection": "stock_documents",
                               "score": 0.6927993893623352
                           }
                       },...
                   ]
               },
               {
                   "type": "text",
                   "text": "**Context Information**:\nBelow is important information to help you provide the most accurate and relevant ...",
               }
           ],
           "is_error": false
       },
       {
           "type": "text",
           "start_timestamp": "2025-09-24T11:34:15.335210Z",
           "stop_timestamp": "2025-09-24T11:34:18.284533Z",
           "text": "The total net sales for March 2025 were $95,359 million, and for March 2024, they were $90,753 million."
       }
   ],
   "model": "private-gpt",
   "stop_reason": "end_turn",
   "stop_sequence": null,
   "usage": {
       "input_tokens": 8121,
       "output_tokens": 42
   }
}