Se usó la API de Cloud Translation para traducir esta página.

Política SemanticCacheLookup

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

Descripción general

La política SemanticCacheLookup es una política de almacenamiento en caché avanzada diseñada para optimizar el rendimiento de las cargas de trabajo de IA, en particular las que involucran modelos de lenguaje grandes (LLM).

La política usa la API de incorporaciones de texto de Vertex AI para generar incorporaciones de texto y la Búsqueda de vectores para encontrar instrucciones similares basadas en la similitud semántica, en lugar de coincidencias exactas.

La política SemanticCacheLookup puede reducir los tiempos de respuesta para las búsquedas repetidas y optimizar los costos, ya que disminuye el volumen de llamadas a los LLM.

Esta política se usa junto con la política SemanticCachePopulate.

Esta política es una política extensible, y el uso de esta política puede tener implicaciones de costo o uso, según tu licencia de Apigee. Para obtener información sobre los tipos de políticas y sus implicaciones de uso, consulta Tipos de políticas.

Antes de comenzar

Antes de usar la política SemanticCacheLookup, debes completar las siguientes tareas:

Crea un proyecto de Vertex AI.
Crea un índice de Vector Search.
Crea un extremo de Vertex AI para el índice.
Crea una política de SemanticCachePopulate.

Para obtener más información sobre cómo completar estas tareas, consulta Comienza a usar las políticas de almacenamiento en caché semántico.

Roles requeridos

Para obtener los permisos que necesitas para aplicar y usar la política SemanticCacheLookup, pídele a tu administrador que te otorgue el rol de IAM de Usuario de AI Platform (roles/aiplatform.user) en la cuenta de servicio que usas para implementar proxies de Apigee. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Habilita las APIs

Enable the Compute Engine, Vertex AI, and Cloud Storage APIs.

Enable the APIs

Elemento `<SemanticCacheLookup>`

Define una política SemanticCacheLookup.

Valor predeterminado	Consulta la pestaña Política predeterminada, a continuación
¿Es obligatorio?	Obligatorio
Tipo	Objeto complejo
Elemento principal	N/A
Elementos secundarios	`<DisplayName>` `<IgnoreUnresolvedVariables>` `<UserPromptSource>` `<Embeddings>` `<SimilaritySearch>`

El elemento <SemanticCacheLookup> usa la siguiente sintaxis:

Sintaxis

El elemento <SemanticCacheLookup> usa la siguiente sintaxis:

<SemanticCacheLookup async="false" continueOnError="false" enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
      <Threshold>0.95</Threshold>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Política predeterminada

En el siguiente ejemplo, se muestra la configuración predeterminada cuando agregas una política SemanticCacheLookup a tu flujo en la IU de Apigee:

<SemanticCacheLookup async="false" continueOnError="false"enabled="true" name="SCL-lookup">
  <DisplayName>SCL-lookup</DisplayName>
  <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  <UserPromptSource>{jsonPath($.contents[-1].parts[-1].text,request.content,true)}</UserPromptSource>
  <Embeddings>
    <VertexAI>
      <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict
      </URL>
    </VertexAI>
  </Embeddings>
  <SimilaritySearch>
    <VertexAI>
      <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
      <Threshold>0.9</Threshold>
      <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Cuando insertas una nueva política SemanticCacheLookup en la IU de Apigee, la plantilla contiene stubs para todas las operaciones posibles. Consulta la información que aparece a continuación sobre los elementos obligatorios.

Este elemento tiene los siguientes atributos, que son comunes a todas las políticas:

Atributo	Predeterminado	¿Es obligatorio?	Descripción
`name`	N/A	Obligatorio	El nombre interno de la política. El valor del atributo `name` puede contener letras, números, espacios, guiones, guiones bajos y puntos. Este valor no puede superar los 255 caracteres. Opcionalmente, usa el elemento `<DisplayName>` para etiquetar la política en el editor de proxy de la interfaz de gestión con un nombre diferente en lenguaje natural.
`continueOnError`	falso	Opcional	Asigna el valor `false` para devolver un error cuando falle una política. Este es el comportamiento esperado de la mayoría de las políticas. Asigna el valor `true` para que la ejecución del flujo continúe incluso después de que falle una política. Consulta también: Las reglas de errores solo se activan cuando hay un error (sobre continueOnError) Gestionar fallos en el flujo actual
`enabled`	true	Opcional	Asigna el valor `true` para aplicar la política. Selecciona `false` para desactivar la política. La política no se aplicará aunque siga adjunta a un flujo.
`async`	falso	Obsoleto	Este atributo está obsoleto.

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <SemanticCacheLookup>:

Elemento secundario	¿Es obligatorio?	Descripción
`<DisplayName>`	Opcional	Es el nombre de la política.
`<IgnoreUnresolvedVariables>`	Opcional	Determina si el procesamiento se detiene cuando una variable no se resuelve. Configúralo como `true` para ignorar las variables sin resolver y continuar con el procesamiento.
`<UserPromptSource>`	Opcional	Ubicación de la carga útil del texto de la instrucción del usuario que se extraerá. Solo se admiten valores de texto de cadena. Este campo admite la sintaxis de plantillas de mensajes de Apigee, incluido el uso de variables o funciones de JSON Path. Por ejemplo: {jsonPath($.contents[-1].parts[-1].text,request.content,true)}
`<Embeddings>`	Obligatorio	Elemento que contiene la información necesaria para generar incorporaciones.
`<SimilaritySearch>`	Obligatorio	Elemento que contiene la información necesaria para realizar búsquedas de similitud. Para obtener más información, consulta Consulta un índice público para obtener los vecinos más cercanos.

Referencia del elemento secundario

En esta sección, se describen los elementos secundarios de <SemanticCacheLookup>.

`<DisplayName>`

Se usa junto con el atributo name para etiquetar la política en el editor de proxy de la interfaz de usuario de gestión con un nombre diferente que suene más natural.

El elemento <DisplayName> es común a todas las políticas.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional. Si omite `<DisplayName>`, se usará el valor del atributo `name` de la política.
Tipo	Cadena
Elemento principal	<`PolicyElement`>
Elementos secundarios	Ninguno

El elemento <DisplayName> utiliza la siguiente sintaxis:

Sintaxis

<PolicyElement>
  <DisplayName>POLICY_DISPLAY_NAME</DisplayName>
  ...
</PolicyElement>

Ejemplo

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

El elemento <DisplayName> no tiene atributos ni elementos secundarios.

<IgnoreUnresolvedVariables>

Determina si el procesamiento se detiene cuando una variable no se resuelve. Configúralo como true para ignorar las variables sin resolver y continuar con el procesamiento.

IgnoreUnresolvedVariables no es aplicable cuando se proporciona <DefaultValue>.

Valor predeterminado	Falso
¿Es obligatorio?	Opcional
Tipo	Booleano
Elemento principal	`<SemanticCacheLookup>`
Elementos secundarios	Ninguno

`<UserPromptSource>`

Ubicación de la carga útil del texto de la instrucción del usuario que se extraerá. Solo se admiten valores de texto de cadena.

Este campo admite la sintaxis de plantillas de mensajes de Apigee, incluido el uso de variables o funciones de JSON Path.

Por ejemplo:

{jsonPath($.contents[-1].parts[-1].text,request.content,true)}

Valor predeterminado	{jsonPath($.contents[-1].parts[-1].text,request.content,true)}
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	`<SemanticCacheLookup>`
Elementos secundarios	Ninguno

`<Embeddings>`

Este elemento contiene la información necesaria para generar embeddings de texto.

Valor predeterminado	N/A
¿Es obligatorio?	Opcional
Tipo	String
Elemento principal	`<SemanticCacheLookup>`
Elementos secundarios	`<VertexAI>`

El elemento <Embeddings> usa la siguiente sintaxis:

<Embeddings>
  <VertexAI>
    <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
  </VertexAI>
</Embeddings>

<VertexAI> (secundario de `<Embeddings>`)

Contiene el elemento <URL> para los atributos específicos de Vertex AI.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	`<Embeddings>`
Elementos secundarios	`<URL>`

El elemento VertexAI usa la siguiente sintaxis:

<VertexAI>
  <URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>
</VertexAI>

<URL> (secundario de `<VertexAI>`)

Es la URL que se usa para generar embeddings de texto. Consulta Modelos compatibles para obtener una lista de los modelos que pueden proporcionar incorporaciones de texto para la política SemanticCacheLookup.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	`<VertexAI>`
Elementos secundarios	Ninguno

El elemento URL usa la siguiente sintaxis:

<URL>https://{LOCATION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{LOCATION}/publishers/google/models/{MODEL_ID}:predict</URL>

`<SimilaritySearch>`

Este elemento contiene la información necesaria para realizar búsquedas de similitud.

Para obtener más información, consulta Consulta un índice público para obtener los vecinos más cercanos.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	`<SemanticCacheLookup>`
Elementos secundarios	`<VertexAI>`

El elemento <SimilaritySearch> usa la siguiente sintaxis:

<SimilaritySearch>
  <VertexAI>
    <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors
    </URL>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (secundario de `<SimilaritySearch>`)

Contiene el elemento <URL> para los atributos específicos de Vertex AI.

Valor predeterminado	N/A
¿Es obligatorio?	Obligatorio
Tipo	String
Elemento principal	`<SimilaritySearch>`
Elementos secundarios	`<URL>`

El elemento VertexAI usa la siguiente sintaxis:

<VertexAI>
  <URL>https://{PUBLIC_DOMAIN_NAME}/v1/projects/{PROJECT_ID}/locations/{LOCATION}/indexEndpoints/{INDEX_ENDPOINT_ID}:findNeighbors</URL>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

En la siguiente tabla, se proporciona una descripción de alto nivel de los elementos secundarios de <VertexAI>.

Elemento secundario ¿Es obligatorio? Descripción

Elemento secundario	¿Es obligatorio?	Descripción
`<URL>`	Obligatorio	String Es la URL que se usa para realizar búsquedas de similitud. El punto de datos que mejor coincida, según el umbral de similitud, será el único que se use.
`<Threshold>`	Opcional	String Es la puntuación de similitud que se usa para determinar si dos instrucciones se consideran una coincidencia. Debe ser un valor entre 0 y 1. El valor predeterminado es 0.9.
`<DeployedIndexID>`	Obligatorio	String Es el ID del índice implementado en el extremo del índice que se usa para el almacenamiento en caché semántico.

<URL>

Obligatorio

String

Es la URL que se usa para realizar búsquedas de similitud. El punto de datos que mejor coincida, según el umbral de similitud, será el único que se use.

<Threshold>

Opcional

String

Es la puntuación de similitud que se usa para determinar si dos instrucciones se consideran una coincidencia. Debe ser un valor entre 0 y 1.

El valor predeterminado es 0.9.

<DeployedIndexID>

Obligatorio

String

Es el ID del índice implementado en el extremo del índice que se usa para el almacenamiento en caché semántico.

Variables de flujo

Las variables de flujo se pueden usar a fin de configurar el comportamiento del entorno de ejecución dinámico de las políticas y los flujos, según los encabezados HTTP, el contenido del mensaje, o el contexto disponible en el flujo. Para obtener más información sobre las variables de flujo, consulta Referencia de variables de flujo.

La política puede establecer estas variables de solo lectura durante la ejecución.

Nombre de la variable	Descripción
`request.content`	Contiene el contenido completo de la solicitud entrante a la API.
`request.url`	Contiene la URL de la solicitud a la API entrante.
`semanticcache.lookup.policy_name.user_prompt`	Contiene componentes específicos extraídos de la instrucción de la solicitud, que se usa para generar incorporaciones o realizar búsquedas de similitud.
`semanticcache.lookup.policy_name.embeddings_request`	Contiene la carga útil de la solicitud enviada a la API de Vertex AI Embeddings para generar incorporaciones de texto para el texto de entrada.
`semanticcache.lookup.policy_name.embeddings_response`	Contiene la respuesta de la API de Vertex AI Embeddings, que incluye los embeddings de texto generados.
`semanticcache.lookup.policy_name.dense_embeddings`	Contiene los valores de incorporación numéricos reales que genera la API de Vertex AI Embeddings.
`semanticcache.lookup.policy_name.is_nearest_neighbor_hit`	Especifica si se encontró un vecino más cercano en la base de datos de vectores para la solicitud determinada y si el punto de datos cumple con el umbral de similitud.
`semanticcache.lookup.policy_name.cache_hit`	Especifica si se encontró la respuesta en la caché semántica.
`semanticcache.lookup.policy_name.cached_llm_response`	Contiene la respuesta recuperada de la caché semántica (si se produjo un acierto de caché).

Referencia de errores

En esta sección, se describen los códigos de falla y los mensajes de error que se muestran, y las variables de falla que establece Apigee específicas para la política <SemanticCacheLookup>. Esta información es importante para saber si estás desarrollando reglas de fallas con el propósito de manejar fallas. Para obtener más información, consulta Lo que necesitas saber sobre los errores de políticas y Controla fallas.

Errores de entorno de ejecución

Estos errores pueden producirse cuando se ejecuta la política.

Código de falla	Estado de HTTP	Causa
`steps.semanticcache.lookup.MessageTemplateExtractionFailed`	`400`	No se pudieron extraer los datos de la solicitud con la expresión de ruta JSON.
`steps.semanticcache.lookup.FailedToExtractUserPrompt`	`500`	No se pudo extraer la instrucción del usuario de la solicitud de la API.
`steps.semanticcache.lookup.EmbeddingsServiceUnavailable`	`400`	El servicio de Vertex AI Embeddings no está disponible en este momento.
`steps.semanticcache.lookup.EmbeddingsAPIFailed`	`400`	Falló el servicio de Vertex AI Embeddings.
`steps.semanticcache.lookup.VectorSearchServiceUnavailable`	`400`	El servicio de Vertex AI Vector Search no está disponible en este momento.
`steps.semanticcache.lookup.VectorSearchAPIFailed`	`400`	Se produjo un error en el servicio de Vertex AI Vector Search.
`steps.semanticcache.lookup.AuthenticationFailure`	`500`	La cuenta de servicio no tiene los permisos necesarios.
`steps.semanticcache.lookup.InternalError`	`500`	Se produjo un error inesperado en la política de SemanticCacheLookup.
`steps.semanticcache.lookup.CalloutError`	`500`	No se pudo realizar la llamada al servicio de Vertex AI.

Errores en la implementación

Estos errores pueden generarse cuando implementas un proxy que contiene esta política.

Nombre del error	Causa
`The Embeddings/VertexAI element is required.`	Se produce si el elemento <VertexAI> en <Embeddings> está vacío.
`The SimilaritySearch/VertexAI element is required.`	Se produce si el elemento <VertexAI> en <SimilaritySearch> está vacío.
`The Embeddings/URL element is required.`	Se produce si el elemento <URL> en <Embeddings> está vacío.
`The SimilaritySearch/URL element is required.`	Se produce si el elemento <URL> en <SimilaritySearch> está vacío.
`Embeddings URL {url} is invalid.`	Se produce si el elemento <URL> en <Embeddings> está vacío o no es válido.
`The SimilaritySearch URL {url} is invalid.`	Se produce si el elemento <URL> en <SimilaritySearch> está vacío o no es válido.
`The scheme {http-scheme} of Embeddings URL {url} must be one of http, https.`	Se produce si el esquema `http` del elemento Embeddings <URL> no es válido.
`The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https.`	Se produce si el esquema `http` del elemento <URL> de SimilaritySearch no es válido.
`SimilaritySearch/Threshold element must be >= 0 and <= 1.`	Si el atributo no está entre 0 y 1, fallará la implementación del proxy de API.
`SimilaritySearch/DeployedIndexID element is required.`	Se produce si el elemento <DeployedIndexID> en <SimilaritySearch> está vacío.
`SimilaritySearch/DeployedIndexID element must not contain spaces.`	Se produce si el elemento <DeployedIndexID> en <SimilaritySearch> contiene espacios.

Variables con fallas

Estas variables se configuran cuando esta política activa un error en el entorno de ejecución. Para obtener más información, consulta Qué debes saber sobre los errores de la política.

Variables	Donde	Ejemplo
`fault.name="FAULT_NAME"`	`FAULT_NAME` es el nombre de la falla, como se indica en la tabla de Errores del entorno de ejecución anterior. El nombre de la falla es la última parte del código de la falla.	`fault.name Matches "UnresolvedVariable"`
`semanticcachelookup.POLICY_NAME.failed`	`POLICY_NAME` es el nombre especificado por el usuario de la política que generó la falla.	`semanticcachelookup.SC-lookup.failed = true`

Ejemplo de respuesta de error

Nota: Para controlar errores, se recomienda capturar la parte errorcode de la respuesta de error. No dependas del texto en la faultstring, ya que podría cambiar.

{
  "fault": {
    "faultstring": "SemanticCacheLookup[SC-lookup]: unable to resolve variable [variable_name]",
    "detail": {
      "errorcode": "steps.semanticcachelookup.UnresolvedVariable"
    }
  }
}

Ejemplo de regla de falla

<FaultRule name="SemanticCacheLookup Faults">
    <Step>
        <Name>SCL-CustomSetVariableErrorResponse</Name>
        <Condition>(fault.name = "SetVariableFailed")</Condition>
    </Step>
    <Condition>(semanticcachelookup.failed = true)</Condition>
</FaultRule>

Esquemas

Un esquema XML (.xsd) define cada tipo de política. Como referencia, los esquemas de políticas están disponibles en GitHub.

Política SemanticCacheLookup Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Descripción general

Antes de comenzar

Roles requeridos

Habilita las APIs

Elemento <SemanticCacheLookup>

Sintaxis

Política predeterminada

Referencia del elemento secundario

<DisplayName>

Sintaxis

Ejemplo

<IgnoreUnresolvedVariables>

<UserPromptSource>

<Embeddings>

<VertexAI> (secundario de <Embeddings>)

<URL> (secundario de <VertexAI>)

<SimilaritySearch>

<VertexAI> (secundario de <SimilaritySearch>)

Variables de flujo

Referencia de errores

Errores de entorno de ejecución

Errores en la implementación

Variables con fallas

Ejemplo de respuesta de error

Ejemplo de regla de falla

Esquemas

Política SemanticCacheLookup

Elemento `<SemanticCacheLookup>`

`<DisplayName>`

`<UserPromptSource>`

`<Embeddings>`

<VertexAI> (secundario de `<Embeddings>`)

<URL> (secundario de `<VertexAI>`)

`<SimilaritySearch>`

<VertexAI> (secundario de `<SimilaritySearch>`)