Sincronizar la base de conocimiento inmediatamente

Permite activar de inmediato la sincronización incremental del conocimiento con fuente de la base de conocimiento; actualmente solo se admite la fuente Google Drive.

Nota:

La interfaz responde inmediatamente tras completar la validación y la planificación, por lo que lo que devuelve es «aceptado», no «actualizado».

Límite de frecuencia: como máximo 1 vez por minuto por cada Agent / Workflow.

Método de solicitud

POST

URL de la solicitud

Elija la ruta correspondiente según el tipo de recurso al que pertenece la API Key. Los parámetros de solicitud, la estructura de respuesta y las reglas de limitación de frecuencia de ambas interfaces son completamente idénticos.

• Agent:

https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync

• Workflow:

https://api-${endpoint}.gptbots.ai/v1/workflow/knowledge-base/sync

Las descripciones de solicitud / respuesta que figuran a continuación se aplican a ambas rutas; los ejemplos se escriben con la ruta de Agent.

Autenticación de la solicitud

Para más detalles, consúltese las instrucciones de autenticación en Visión general de la API (API Overview).

Solicitud

Ejemplo de solicitud

• Sincronizar bases de conocimiento específicas:

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive",
    "knowledge_base_ids": ["6a44c3512ceb43775567391c", "6a44c3512ceb43775567391d"]
}'

                    

• Sincronizar todas las bases de conocimiento de este Agent:

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive"
}'

                    

Cabeceras de la solicitud

Parámetros de la solicitud

Respuesta

Ejemplo de respuesta

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "accepted": true,
        "source": "google-drive",
        "matched_knowledge_base_count": 2,
        "matched_doc_count": 37,
        "matched_folder_count": 3,
        "skipped": [
            {
                "reason": "DRIVE_NOT_AUTHORIZED",
                "message": "The document owner has not authorized Google Drive, or the authorization has expired.",
                "knowledge_base_id": "6a44c3512ceb43775567391e",
                "doc_count": 8
            },
            {
                "reason": "KNOWLEDGE_BASE_NOT_FOUND",
                "message": "Knowledge base does not exist or does not belong to this agent.",
                "knowledge_base_id": "deadbeefdeadbeefdeadbeef"
            }
        ],
        "scheduled_round_running": false
    }
}

                    

Respuesta correcta

Valores de skipped[].reason

Respuesta fallida

Códigos de error habituales:

Ejemplo de respuesta cuando source no es válido:

                      
                      {
    "code": 40000,
    "message": "Unsupported source: sharepoint. Supported: google-drive"
}

                    

Instrucciones de uso

Lo que devuelve es «aceptado», no «completado»

La interfaz responde inmediatamente tras completar la validación y la planificación; la extracción, el análisis y la vectorización reales se ejecutan de forma asíncrona en segundo plano. Por lo tanto, matched_doc_count es «cuántos documentos se comprobarán en esta ocasión», no «cuántos documentos se actualizaron». Para confirmar el resultado final, sondee la interfaz Obtener la lista de documentos para ver el estado de los documentos; cuando el estado del documento cambia a AVAILABLE, significa que ese documento ha terminado de sincronizarse.

Solo hace incremental, no consume cuota de forma repetida

Para cada documento, el sistema compara primero la última hora de modificación en Google Drive:

• El documento de origen no ha cambiado: se omite, no se vuelve a descargar, ni a analizar, ni consume cuota.
• El documento de origen ha cambiado: se vuelve a extraer, analizar y vectorizar.
• Hay archivos nuevos en la carpeta vinculada: se agregan automáticamente como documentos de conocimiento.

Por lo tanto, llamar a esta interfaz de forma repetida es seguro; el contenido no modificado no genera costes adicionales.

Esta interfaz no puede reintentar documentos cuyo análisis ha fallado

El juicio incremental solo tiene en cuenta si el documento de origen en Google Drive ha cambiado, no el estado actual del documento.

Por lo tanto, un documento cuyo análisis falló anteriormente (con estado FAIL), mientras su archivo de origen en Google Drive no se haya modificado, no se volverá a procesar al llamar a esta interfaz: se tratará como «documento de origen sin cambios» y se omitirá directamente, su estado se mantendrá igual y tampoco aparecerá en skipped.

Para reintentar documentos cuyo análisis ha fallado, utilice la interfaz Reincorporar documentos fallidos. O bien realice una modificación en el archivo de origen en Google Drive para que se actualice su última hora de modificación, y así esta interfaz podrá volver a extraerlo.

La sincronización elimina documentos de conocimiento

Esta interfaz no solo agrega y actualiza, sino que también elimina documentos de conocimiento según el estado actual de Google Drive.

Cuando la carpeta de Google Drive vinculada queda vacía, se eliminan todos los documentos de conocimiento ya importados de esa carpeta. La condición de activación es que la carpeta siga siendo accesible en Google Drive pero no se pueda enumerar ningún archivo. El sistema valida primero la accesibilidad de la carpeta y, cuando no puede obtener los metadatos de la carpeta (carpeta movida, cambio de permisos, temporalmente inaccesible, etc.), omite la eliminación para evitar borrados accidentales.

El ámbito de la eliminación se limita a «esa carpeta + esa base de conocimiento». Cuando una misma carpeta de Google Drive es referenciada por varias bases de conocimiento, estas no se afectan entre sí.

Este comportamiento es coherente con la sincronización programada del sistema; esta interfaz solo hace que ocurra antes. Sin embargo, dado que esta interfaz también cubre los documentos que no tenían configurado un plan de sincronización programada al importarse (documentos que originalmente ningún flujo automático eliminaría), antes de llamarla confirme que el contenido de la carpeta en Google Drive es el esperado.

Ámbito de cobertura

El ámbito de la sincronización cubre todos los documentos de la base de conocimiento procedentes de Google Drive, incluida la parte que no tenía configurado un plan de sincronización programada al importarse: esos documentos no son procesados por las rondas programadas del sistema y solo pueden actualizarse mediante esta interfaz.

Limitación de frecuencia

• Como máximo 1 vez por minuto por cada Agent / Workflow. Ambas rutas comparten el mismo contador; cambiar de ruta no elude la limitación.
• También está sujeta al límite de solicitudes por minuto (RPM) de las API de tipo base de conocimiento del plan de la organización, y comparte esa cuota con las demás interfaces de base de conocimiento.
• Cuando la sincronización anterior del mismo Agent / Workflow aún no ha terminado de ejecutarse, una nueva llamada devuelve accepted=false y reason=SYNC_IN_PROGRESS.

Relación con la sincronización programada

Esta interfaz y la sincronización programada del sistema son independientes entre sí y no se bloquean mutuamente. Cuando scheduled_round_running es true, esta solicitud se sigue aceptando y no se rechaza porque haya una ronda programada en ejecución.

Cuando ambas procesan el mismo documento al mismo tiempo, no se genera contenido duplicado: el sistema realiza el juicio incremental según la última hora de modificación del documento de origen y los archivos ya importados no se vuelven a crear.

La sincronización programada se ejecuta automáticamente según la frecuencia configurada en la propia base de conocimiento, mientras que esta interfaz ignora dicha frecuencia y se activa de inmediato. Ambas se complementan: la sincronización programada se encarga de la actualización habitual y esta interfaz se encarga del escenario «quiero sincronizar ahora mismo».