La API es compatible con flujos de trabajo para administrar colecciones y documentos, procesar contenido y aplicar capacidades de IA como respuesta a preguntas, resumen, búsqueda y extracción estructurada.Use esta página para comprender cómo funcionan estas piezas juntas, luego use la referencia de la API para obtener detalles de implementación a nivel de punto final.
Asegúrate de tener:
Si no ha configurado el acceso de la API, consulte Configurar acceso de la API de Base de conocimiento.
Un flujo de trabajo típico de la API de Base de conocimiento sigue esta secuencia:
Autenticación → Colección → Documento → Índice → Inferencia → Respuesta
Una colección define el dominio de conocimiento con el que trabaja tu aplicación.Cuando creas una colección, la respuesta incluye su espacio de nombres único, que usas en operaciones posteriores.
Por ejemplo:
{
"namespace": "<collection-namespace>",
"name": "example-collection"
}
Conserve el espacio de nombres de la colección para las solicitudes de documento e inferencia.
Los documentos se cargan en colecciones y se les asignan identificadores de documento únicos.
Una respuesta de carga identifica el documento para que su aplicación pueda realizar el seguimiento del procesamiento y hacer referencia a él en solicitudes posteriores.
{
"document_id": "<document-id>",
"document_name": "example.pdf"
}
Cargar un documento e indexarlo son fases separadas.
La carga transfiere el archivo a Knowledge Base.La indexación extrae su contenido y procesa ese contenido para su uso por operaciones de IA.
Su aplicación debe confirmar que el procesamiento se ha completado antes de enviar solicitudes de inferencia contra el documento.
Las operaciones de inferencia aplican las capacidades de IA de Knowledge Base al contenido procesado.
Las operaciones disponibles incluyen:
Use la referencia de la API para determinar el punto final y el esquema de solicitud para la operación que desea realizar.
Las respuestas de inferencia devuelven el resultado generado y pueden incluir información de atribución complementaria.
Según la operación, los datos de atribución pueden identificar el contenido fuente, la página y las coordenadas asociadas con el resultado.Su aplicación determina cómo se presenta esa información al usuario.
El flujo de trabajo de aplicación más simple es crear una colección, agregar un documento, esperar el procesamiento y luego ejecutar una operación de inferencia.
Cree la colección que contendrá los documentos fuente para su aplicación.
Conserve el espacio de nombres devuelto en la respuesta:
collection_namespace = <returned-namespace>
Usará este valor cuando agregue documentos e invoque operaciones contra la colección.
Cargue un documento a la colección y conserve el ID de documento devuelto:
document_id = <returned-document-id>
El ID del documento identifica el documento cargado independientemente de su nombre de archivo.
Inicie la operación de indexación requerida y, a continuación, compruebe el estado del documento hasta que se complete el procesamiento.
No asuma que una carga exitosa significa que el documento está listo para operaciones de IA.
Un flujo de aplicación típico es:
Cargar documento
↓
Iniciar indexación
↓
Verificar estado de procesamiento
↓
Completado
Si el procesamiento falla, resuelva el problema de procesamiento del documento antes de enviar una solicitud de inferencia.
Una vez completado el procesamiento, envía el espacio de nombres de la colección, el ID del documento y cualquier entrada específica de la operación requerida por el punto final.
Por ejemplo, una solicitud de respuesta a preguntas conceptualmente proporciona:
Colección: <collection-namespace>
Documento: <document-id>
Pregunta: ¿Cuáles son los hallazgos clave?
Utiliza la referencia de la API para el esquema de solicitud actual.
Utiliza la respuesta devuelta o los datos extraídos en tu aplicación.
Si la respuesta incluye información de atribución, puedes usarla para conectar la información generada con el contenido del documento que la respalda.
El ciclo de vida del documento afecta cuándo tu aplicación puede utilizar el contenido cargado.
| Planificación | Qué sucede | Acción de la aplicación |
|---|---|---|
| Cargar | El archivo se agrega a la Base de Conocimiento y recibe un ID de documento. | Conserva el ID del documento. |
| Indexación | El contenido se extrae y procesa para uso de IA. | Monitoriza el estado del documento. |
| Finalizado | El contenido procesado está disponible para realizar inferencias. | Enviar solicitudes de IA. |
| Error | El procesamiento no se completó correctamente. | Resolver el fallo antes de continuar. |
Esta distinción es particularmente importante para flujos de trabajo automatizados.Una aplicación debe verificar el estado del procesamiento en lugar de enviar inmediatamente una solicitud de inferencia después de la carga.
Elige la operación en función de lo que tu aplicación necesite hacer con el contenido fuente.
Utiliza las preguntas y respuestas para enviar preguntas en lenguaje natural sobre el contenido de la colección o documento.
La API proporciona preguntas y respuestas tanto con flujo como sin flujo.
Las preguntas y respuestas con flujo devuelven la respuesta de forma incremental conforme se genera. Úsalo cuando tu interfaz deba mostrar contenido generado de forma progresiva.
Las preguntas y respuestas con flujo también admiten controlar si las instrucciones personalizadas se aplican a la solicitud. También puedes controlar si se genera razonamiento para una respuesta de preguntas y respuestas en streaming.
Las preguntas y respuestas sin streaming esperan a que se complete la generación y devuelven la respuesta finalizada.Úsalo cuando tu aplicación no necesite mostrar resultados parciales.
Usa el resumen para generar una representación condensada del contenido del documento.
La referencia de la API define los requisitos de la solicitud actuales y los datos de entrada compatibles.
Usa la búsqueda de contexto para recuperar contenido relevante para el texto de búsqueda especificado.
Esto puede ayudar a las aplicaciones a identificar material fuente relevante sin generar una respuesta conversacional.
Usa la extracción cuando tu aplicación necesite valores estructurados del contenido del documento.
Una definición de extracción puede identificar información como:
Nombre de la propiedad: contract_value
Tipo: integer
Descripción: Valor del contrato del acuerdo
Indicación: Extrae el mayor valor del acuerdo en dólares.
El resultado devuelto puede incluir el valor extraído, información sobre el nivel de confianza y atribución de fuente.
La API proporciona varias formas de determinar qué contenido participa en una solicitud.
Usa los identificadores de colección y documento para definir el contenido principal disponible para una operación.
Las etiquetas se asocian con documentos en lugar de con colecciones.
Las etiquetas de documento están disponibles solo a través de la API de Knowledge Base y no se muestran en la interfaz de usuario estándar.
Puedes usar etiquetas con operaciones compatibles para filtrar los documentos considerados para una solicitud. Por ejemplo, una aplicación podría etiquetar un grupo de documentos como documentos financieros y restringir una pregunta a documentos que tengan esa etiqueta.
Los archivos adjuntos son independientes de los documentos de la colección.
Agregar un archivo adjunto a una conversación no añade ese archivo a la colección.El archivo adjunto aún puede aportar contexto a una respuesta generada, junto con el contenido de la colección y el historial del chat.
Usa los puntos finales de archivos adjuntos cuando tu aplicación necesite contenido temporal o específico de la conversación sin añadirlo permanentemente a una colección.
Las respuestas de inferencia pueden incluir información de atribución que conecta la salida generada con el contenido de la fuente de apoyo.
Los datos de atribución pueden incluir información como:
La API proporciona esta información como datos.Tu aplicación es responsable de decidir cómo presentarla.
Por ejemplo, una aplicación puede usar las coordenadas devueltas para crear una experiencia de resaltado de fuente que identifique la ubicación que respalda una respuesta generada.
Las operaciones de la API usan los permisos disponibles para la identidad autenticada.
Una solicitud puede fallar si la identidad autenticada carece de acceso a la colección, documento u operación solicitada.
Al solucionar problemas:
El X-Request-ID identifica la solicitud a través de los servicios de Knowledge Base y puede ayudar al Soporte a investigar una solicitud fallida.
Utiliza la demostración de Python cuando quieras ejemplos funcionales que demuestren estos conceptos en una aplicación.
Empezar con la demostración de Python de Knowledge Base
Utiliza la referencia de la API cuando estés listo para implementar una operación específica.
