Política SemanticCacheLookup

Política extensível

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

A política SemanticCacheLookup é uma política avançada de armazenamento em cache projetada para otimizar o desempenho das cargas de trabalho de IA, principalmente aquelas que envolvem modelos de linguagem grandes (LLMs).

A política usa a API Text embeddings da Vertex AI para gerar embeddings de texto e a Pesquisa vetorial para encontrar comandos semelhantes com base na similaridade semântica, em vez de correspondências exatas.

A política SemanticCacheLookup reduz os tempos de resposta para consultas repetidas e otimiza os custos ao diminuir o volume de chamadas para LLMs.

Essa política funciona em conjunto com a política SemanticCachePopulate.

Esta é uma política extensível. O uso dela pode ter implicações no custo ou na utilização, dependendo da sua licença da Apigee. Para informações sobre tipos de política e implicações de uso, consulte Tipos de política.

Observação:se você configurou um proxy de encaminhamento para seu ambiente, as chamadas de saída que essa política faz para a Vertex AI são encaminhadas pelo proxy. Não é necessário fazer nenhuma configuração no nível da política. Isso se aplica à Apigee e à Apigee híbrida 1.16.10 e mais recentes, e 1.17.0 e mais recentes. Para mais informações, consulte Configurar proxy de encaminhamento (Apigee) ou Configurar proxy de encaminhamento para proxies de API (Apigee Hybrid).

Antes de começar

Antes de usar a política SemanticCacheLookup, conclua as seguintes tarefas:

• Crie um projeto da Vertex AI.
• Crie um índice de pesquisa de vetor.
• Crie um endpoint da Vertex AI para o índice.
• Crie uma política SemanticCachePopulate.

Para mais informações sobre como concluir essas tarefas, consulte Começar a usar políticas de cache semântico.

Funções exigidas

Para receber as permissões necessárias para aplicar e usar a política SemanticCacheLookup, peça ao administrador para conceder a você o papel do IAM de Usuário da AI Platform (roles/aiplatform.user) na conta de serviço usada para implantar proxies do Apigee. Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar APIs

Ative as APIs Compute Engine, Vertex AI e Cloud Storage, se alguma delas ainda não estiver ativada.

Funções necessárias para ativar APIs

Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão pelo papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão pelo papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

Ativar as APIs

Elemento <SemanticCacheLookup>

Define uma política SemanticCacheLookup.

Valor padrão	Consulte a guia Política padrão a seguir
Obrigatório?	Obrigatório
Tipo	Objeto complexo
Elemento pai	N/A
Elemento filho	<DisplayName> <IgnoreUnresolvedVariables> <UserPromptSource> <Embeddings> <SimilaritySearch>

O elemento <SemanticCacheLookup> usa a seguinte sintaxe:

Sintaxe

O elemento <SemanticCacheLookup> usa a seguinte sintaxe:

<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>
      <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Política padrão

O exemplo a seguir mostra as configurações padrão quando você adiciona uma política SemanticCacheLookup ao fluxo na interface da 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>
      <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
    </VertexAI>
  </SimilaritySearch>
</SemanticCacheLookup>

Quando você insere uma nova política SemanticCacheLookup na interface da Apigee, o modelo contém stubs para todas as operações possíveis. Veja abaixo as informações sobre os elementos obrigatórios.

Este elemento tem os seguintes atributos comuns a todas as políticas:

Atributo	Padrão	Obrigatório?	Descrição
name	N/A	Valor	O nome interno da política. O valor do atributo name pode conter letras, números, espaços, hifens, sublinhados e pontos. Esse valor não pode exceder 255 caracteres. Opcionalmente, use o elemento <DisplayName> para rotular a política no editor de proxy da IU de gerenciamento com um nome de linguagem natural diferente.
continueOnError	falso	Opcional	Defina como false para retornar um erro quando uma política falhar. Esse é o comportamento esperado para a maioria das políticas. Defina como true para que a execução do fluxo continue, mesmo depois que uma política falhar. Consulte também: As regras de falha são acionadas SOMENTE em um estado de erro (sobre continueOnError) Como corrigir falhas no fluxo atual
enabled	true	Opcional	Defina como true para aplicar a política. Defina como false para desativar a política. A política não será aplicada mesmo que permaneça vinculada a um fluxo.
async	falso	Obsoleto	Esse atributo está obsoleto.

A tabela a seguir fornece uma descrição resumida dos elementos filhos de <SemanticCacheLookup>:

Elemento filho	Obrigatório?	Descrição
<DisplayName>	Opcional	O nome da política.
<IgnoreUnresolvedVariables>	Opcional	Determina se o processamento é interrompido quando uma variável não é resolvida. Defina como true para ignorar variáveis não resolvidas e continuar o processamento.
<UserPromptSource>	Opcional	O local do payload para extrair o texto do comando do usuário. Somente valores de texto de string são aceitos. Esse campo aceita a sintaxe de modelo de mensagem da Apigee, incluindo o uso de variáveis ou funções de caminho JSON. Exemplo: {jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
<Embeddings>	Obrigatório	Elemento que contém as informações necessárias para gerar embeddings.
<SimilaritySearch>	Obrigatório	Elemento que contém as informações necessárias para realizar pesquisas de similaridade. Para mais informações, consulte Consultar o índice público para encontrar os vizinhos mais próximos.

Referência a elementos filhos

Esta seção descreve os elementos filhos de <SemanticCacheLookup>.

<DisplayName>

Use além do atributo name para rotular a política no editor de proxy da IU de gerenciamento com um nome de som diferente e mais natural.

O elemento <DisplayName> é comum a todas as políticas.

Valor padrão	N/A
Obrigatório?	Opcional. Se você omitir <DisplayName>, o valor do atributo name da política será usado
Tipo	String
Elemento pai	<PolicyElement>
Elemento filho	Nenhum

O elemento <DisplayName> usa a seguinte sintaxe:

Sintaxe

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

Exemplo

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

O elemento <DisplayName> não tem atributos ou elementos filhos.

<IgnoreUnresolvedVariables>

Determina se o processamento é interrompido quando uma variável não é resolvida. Defina como true para ignorar variáveis não resolvidas e continuar o processamento.

IgnoreUnresolvedVariables não é aplicável quando <DefaultValue> é fornecido.

Valor padrão	Falso
Obrigatório?	Opcional
Tipo	Booleano
Elemento pai	<SemanticCacheLookup>
Elemento filho	Nenhum

<UserPromptSource>

O local do payload para extrair o texto do comando do usuário. Somente valores de texto de string são aceitos.

Esse campo é compatível com a sintaxe de modelo de mensagem da Apigee, incluindo o uso de variáveis ou funções de caminho JSON.

Exemplo:

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

Valor padrão	{jsonPath('$.contents[-1].parts[-1].text',request.content,true)}
Obrigatório?	Opcional
Tipo	String
Elemento pai	<SemanticCacheLookup>
Elemento filho	Nenhum

<Embeddings>

Esse elemento contém as informações necessárias para gerar embeddings de texto.

Valor padrão	N/A
Obrigatório?	Opcional
Tipo	String
Elemento pai	<SemanticCacheLookup>
Elemento filho	<VertexAI>

O elemento <Embeddings> usa a seguinte sintaxe:

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

<VertexAI> (filho de <Embeddings>)

Contém o elemento <URL> para atributos específicos da Vertex AI.

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	String
Elemento pai	<Embeddings>
Elemento filho	<URL>

O elemento VertexAI usa a seguinte sintaxe:

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

<URL> (filho de <VertexAI>)

O URL usado para gerar embeddings de texto. Consulte Modelos compatíveis para ver uma lista de modelos que fornecem embeddings de texto para a política SemanticCacheLookup.

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	String
Elemento pai	<VertexAI>
Elemento filho	Nenhum

O elemento URL usa a seguinte sintaxe:

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

O elemento URL é compatível com o uso de modelos de URL. Se quiser, forneça uma variável nesse elemento para armazenar o valor do URL, como mostrado no exemplo a seguir:

<URL>https://{URL_VARIABLE}</URL>

<SimilaritySearch>

Esse elemento contém as informações necessárias para realizar pesquisas de similaridade.

A pesquisa de similaridade pode ser executada em um índice da Pesquisa de vetor implantado em um endpoint público ou privado (Private Service Connect). É necessário fornecer exatamente um dos seguintes transportes no elemento <VertexAI>:

• <URL>: para um endpoint público, via REST (:findNeighbors).
• <PrivateServiceConnect>: para um endpoint particular, por gRPC. Um endpoint de índice implantado particular (Private Service Connect) aceita apenas gRPC.

Para mais informações, consulte Consultar o índice público para receber os vizinhos mais próximos e Cache semântico com um endpoint particular (Private Service Connect).

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	String
Elemento pai	<SemanticCacheLookup>
Elemento filho	<VertexAI>

O elemento <SimilaritySearch> usa a seguinte sintaxe:

Endpoint público (REST):

<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>
    <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
  </VertexAI>
</SimilaritySearch>

Endpoint particular (Private Service Connect, gRPC):

<SimilaritySearch>
  <VertexAI>
    <PrivateServiceConnect>
      <GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
    </PrivateServiceConnect>
    <Threshold>0.9</Threshold>
    <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
  </VertexAI>
</SimilaritySearch>

<VertexAI> (filho de <SimilaritySearch>)

Contém os atributos específicos da Vertex AI usados para realizar a pesquisa de similaridade. Forneça exatamente um dos seguintes transportes: um elemento <URL> (para um endpoint público, via REST) ou um elemento <PrivateServiceConnect> (para um endpoint particular, via gRPC).

Valor padrão	N/A
Obrigatório?	Obrigatório
Tipo	String
Elemento pai	<SimilaritySearch>
Elemento filho	<URL>

Para um endpoint público, o elemento VertexAI usa a seguinte sintaxe:

<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>
  <DistanceMeasureType>DOT_PRODUCT_DISTANCE</DistanceMeasureType>
</VertexAI>

Para um endpoint particular (Private Service Connect), o elemento VertexAI usa a seguinte sintaxe:

<VertexAI>
  <PrivateServiceConnect>
    <GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint>
  </PrivateServiceConnect>
  <Threshold>0.9</Threshold>
  <DeployedIndexID>{DEPLOYED_INDEX_ID}</DeployedIndexID>
</VertexAI>

A tabela a seguir fornece uma descrição resumida dos elementos filhos de <VertexAI>.

Elemento filho	Obrigatório?	Descrição
<URL>	Obrigatório (forneça <URL> ou <PrivateServiceConnect>)	String O URL usado para realizar pesquisas de similaridade em um endpoint de índice da Pesquisa vetorial pública, via REST (:findNeighbors). O ponto de dados com a maior correspondência, com base no limite de similaridade, é o único usado. O elemento URL é compatível com o uso de modelos de URL. Se quiser, forneça uma variável nesse elemento para armazenar o valor do URL, como mostrado no exemplo a seguir: <URL>https://{URL_VARIABLE}</URL>
<PrivateServiceConnect>	Obrigatório (forneça <URL> ou <PrivateServiceConnect>)	Objeto complexo Contém as informações de conexão usadas para realizar pesquisas de similaridade em um índice privado da Pesquisa vetorial implantado em um endpoint do Private Service Connect. Um endpoint de índice implantado particular aceita apenas gRPC. Observação:o transporte <PrivateServiceConnect> é compatível com a Apigee e a Apigee híbrida versão 1.17.0 e mais recentes. Esse elemento contém um único elemento filho, <GrpcEndpoint>: <PrivateServiceConnect> <GrpcEndpoint>grpc://{TARGET_HOST}:10000</GrpcEndpoint> </PrivateServiceConnect> O elemento <GrpcEndpoint> especifica o endereço gRPC do endpoint privado. Aplicam-se as seguintes regras: O formato é grpc://TARGET_HOST:PORT. O esquema precisa ser grpc://. grpcs:// (TLS) não é compatível com esta versão. TARGET_HOST é o endereço IP de anexo de endpoint ou um registro DNS particular em uma zona de DNS do Cloud DNS com peering. A porta é 10000 para endpoints do plano de dados do Private Service Connect da Pesquisa vetorial. O salto gRPC é texto simples e não autenticado, sendo protegido pelo isolamento de rede. Para mais informações, consulte Armazenamento em cache semântico com um endpoint particular (Private Service Connect).
<Threshold>	Opcional	String O valor que um vizinho mais próximo precisa alcançar para ser considerado uma correspondência. <DistanceMeasureType> define a direção da comparação. O valor padrão é 0,9, que é adequado para DOT_PRODUCT_DISTANCE. Consulte Escolher um limite para sua medida de distância.
<DeployedIndexID>	Obrigatório	String O ID do índice implantado no endpoint do índice usado para cache semântico.
<DistanceMeasureType>	Opcional	String A medida de distância com que seu índice do Vertex AI Vector Search foi criado. Ela define a direção da comparação <Threshold>. Os valores válidos são DOT_PRODUCT_DISTANCE, COSINE_DISTANCE, SQUARED_L2_DISTANCE e L1_DISTANCE, que precisam ser exatamente iguais. Qualquer outro valor causa falha na implantação. Para saber o que cada medida calcula, consulte Parâmetros de configuração de índice. O valor padrão é DOT_PRODUCT_DISTANCE. Consulte Escolher um limite para sua medida de distância.

Escolher um limite para sua medida de distância

A métrica com que seu índice foi criado decide a direção da comparação <Threshold>: o produto escalar é uma semelhança, então um valor maior significa uma correspondência mais próxima, enquanto os outros três são distâncias, em que um valor menor significa uma correspondência mais próxima. Defina <DistanceMeasureType> para corresponder ao seu índice e ajuste o limite dessa métrica.

Observação:o <DistanceMeasureType> está disponível na Apigee 1-18-0-apigee-4 e em versões mais recentes, além da versão 1.17.0 e mais recentes da Apigee híbrida. Em versões anteriores, o elemento é aceito e ignorado silenciosamente, e o limite é comparado como se a medida fosse DOT_PRODUCT_DISTANCE. Marque semanticcache.lookup.policy_name.measure_type em uma sessão de depuração para confirmar a métrica a que a política foi aplicada.

Medida de distância	Limite de cache
DOT_PRODUCT_DISTANCE (padrão)	value >= threshold
COSINE_DISTANCE	value <= threshold
SQUARED_L2_DISTANCE	value <= threshold
L1_DISTANCE	value <= threshold

Observação:o cache semântico recomenda fortemente que todos os vetores sejam normalizados, o que produz o comportamento mais bem definido. Também não é recomendável usar L1_DISTANCE com a normalização L2 (featureNormType: UNIT_L2_NORM), porque a distância é dimensionada com a raiz quadrada da contagem de dimensões do embedding, em vez de ficar em um intervalo fixo.

Para encontrar a medida com que seu índice foi criado, execute gcloud ai indexes describe INDEX_ID --region=REGION e leia o campo distanceMeasureType. Para confirmar a aplicação da política, envie a mesma solicitação duas vezes e inspecione semanticcache.lookup.policy_name.measure_type e semanticcache.lookup.policy_name.nearest_neighbor_measure em uma sessão de depuração.

Variáveis de fluxo

As variáveis de fluxo configuram o comportamento dinâmico de tempo de execução para políticas e fluxos, com base em cabeçalhos HTTP ou conteúdo de mensagens, ou no contexto disponível no fluxo. Para mais informações sobre variáveis de fluxo, consulte a Referência de variáveis de fluxo.

Essa política fornece o seguinte conjunto de variáveis de fluxo somente leitura durante a execução. É possível usar essas variáveis de fluxo com a política DataCapture para criar relatórios de análise personalizados. Para mais informações, consulte Coletar dados do cliente com a política de captura de dados.

Nome da variável	Descrição
request.content	Contém todo o conteúdo da solicitação de API recebida.
request.url	Contém o URL da solicitação de API recebida.
SemanticCacheLookup.policy_name.user_prompt	Contém componentes específicos extraídos do comando da solicitação, que é usado para gerar embeddings ou realizar pesquisas de similaridade.
SemanticCacheLookup.policy_name.embeddings_request	Contém o payload da solicitação enviado à API Embeddings da Vertex AI para gerar embeddings de texto para o texto de entrada.
SemanticCacheLookup.policy_name.embeddings_response	Contém a resposta da API Embeddings da Vertex AI, que inclui os embeddings de texto gerados.
SemanticCacheLookup.policy_name.dense_embeddings	Contém os valores numéricos reais de embedding gerados pela API Vertex AI Embeddings.
SemanticCacheLookup.policy_name.is_nearest_neighbor_hit	Especifica se um vizinho mais próximo foi encontrado no banco de dados de vetores para a solicitação e se o ponto de dados atende ao limite de similaridade.
SemanticCacheLookup.policy_name.cache_hit	Especifica se a resposta foi encontrada no cache semântico.
SemanticCacheLookup.policy_name.cached_llm_response	Contém a resposta recuperada do cache semântico (se ocorreu uma ocorrência em cache).
semanticcache.lookup.policy_name.nearest_neighbor_measure	Contém o valor bruto que o índice da pesquisa vetorial retornou para o vizinho mais próximo. Definido em acertos e erros sempre que um vizinho era retornado.
semanticcache.lookup.policy_name.measure_type	Contém a medida de distância que a política aplicou, incluindo quando ela voltou ao padrão. Definido em acertos e erros sempre que um vizinho é retornado.

Referência de erros

Nesta seção, descrevemos os códigos de falha e as mensagens de erro retornadas pela Apigee, bem como as variáveis de falha definidas pela Apigee, específicas para a política <SemanticCacheLookup>. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros ocorrem quando a política é executada.

Código de falha	Status HTTP	Causa
steps.semanticcache.lookup.MessageTemplateExtractionFailed	400	Não foi possível extrair dados da solicitação usando a expressão JSONPath.
steps.semanticcache.lookup.FailedToExtractUserPrompt	500	Não foi possível extrair o comando do usuário da solicitação de API.
steps.semanticcache.lookup.EmbeddingsServiceUnavailable	400	O serviço de incorporações da Vertex AI está indisponível no momento.
steps.semanticcache.lookup.EmbeddingsAPIFailed	400	O serviço Vertex AI Embeddings falhou.
steps.semanticcache.lookup.VectorSearchServiceUnavailable	400	O serviço Vertex AI Busca Vetorial está indisponível no momento.
steps.semanticcache.lookup.VectorSearchAPIFailed	400	O serviço Vertex AI Busca Vetorial falhou.
steps.semanticcache.lookup.AuthenticationFailure	500	A conta de serviço não tem as permissões necessárias.
steps.semanticcache.lookup.InternalError	500	Ocorreu um erro inesperado na política SemanticCacheLookup.
steps.semanticcache.lookup.CalloutError	500	A chamada de serviço da Vertex AI falhou.

Erros de implantação

Esses erros ocorrem quando você implanta um proxy que contém essa política.

Nome do erro	Causa
The Embeddings/VertexAI element is required.	Ocorre se o elemento <VertexAI> em <Embeddings> estiver vazio.
The SimilaritySearch/VertexAI element is required.	Ocorre se o elemento <VertexAI> em <SimilaritySearch> estiver vazio.
Embeddings/VertexAI cannot have both URL and PrivateServiceConnect elements.	Ocorre se os elementos <URL> e <PrivateServiceConnect> em <Embeddings> forem especificados.
SimilaritySearch/VertexAI cannot have both URL and PrivateServiceConnect elements.	Ocorre se os elementos <URL> e <PrivateServiceConnect> em <SimilaritySearch> forem especificados.
Embeddings/VertexAI/URL or Embeddings/PrivateServiceConnect/GrpcEndpoint element is required.	Ocorre se nem o elemento <URL> nem o elemento <GrpcEndpoint> em <Embeddings> forem especificados.
SimilaritySearch/VertexAI/URL or SimilaritySearch/PrivateServiceConnect/GrpcEndpoint element is required.	Ocorre se nem o elemento <URL> nem o elemento <GrpcEndpoint> em <SimilaritySearch> forem especificados.
The Embeddings/VertexAI/PrivateServiceConnect element is not supported. Use URL instead.	Ocorre se o elemento <PrivateServiceConnect> for usado em <Embeddings>.
Embeddings URL {url} is invalid.	Ocorre se o elemento <URL> em <Embeddings> estiver vazio ou for inválido.
The SimilaritySearch URL {url} is invalid.	Ocorre se o elemento <URL> em <SimilaritySearch> estiver vazio ou for inválido.
The scheme {http-scheme} of Embeddings URL {url} must be one of http, https.	Ocorre se o esquema http do elemento "Embeddings <URL>" for inválido.
The scheme {http-scheme} of SimilaritySearch URL {url} must be one of http, https.	Ocorre se o esquema http do elemento <URL> do SimilaritySearch for inválido.
The SimilaritySearch /VertexAI/PrivateServiceConnect/GrpcEndpoint {grpc-endpoint} must be in the format "grpc://TARGET_HOST:PORT".	Ocorre se o elemento <GrpcEndpoint> em <SimilaritySearch> não estiver no formato grpc://TARGET_HOST:PORT.
The scheme {grpc-scheme} of SimilaritySearch /VertexAI/PrivateServiceConnect/GrpcEndpoint {grpc-endpoint} must be "grpc".	Ocorre se o esquema grpc do elemento <GrpcEndpoint> do SimilaritySearch for inválido.
SimilaritySearch/Threshold element must not be NaN.	Ocorre se o elemento <Threshold> em <SimilaritySearch> for NaN. Infinity e -Infinity são permitidos.
Invalid DistanceMeasureType {value}. Supported values are DOT_PRODUCT_DISTANCE, COSINE_DISTANCE, SQUARED_L2_DISTANCE and L1_DISTANCE	Ocorre se o elemento <DistanceMeasureType> em <SimilaritySearch> não for um dos quatro valores aceitos. A correspondência é exata. Consulte Parâmetros de configuração de índice.
SimilaritySearch/DeployedIndexID element is required.	Ocorre se o elemento <DeployedIndexID> em <SimilaritySearch> estiver vazio.
SimilaritySearch/DeployedIndexID element must not contain spaces.	Ocorre se o elemento <DeployedIndexID> em <SimilaritySearch> contiver espaços.

Variáveis de falha

Essa política define essas variáveis quando aciona um erro no ambiente de execução. Para mais informações, consulte O que você precisa saber sobre erros de política.

Variáveis	Onde	Exemplo
fault.name="FAULT_NAME"	FAULT_NAME é o nome da falha, conforme listado na tabela Erros de ambiente de execução acima. O nome da falha é a última parte do código de falha.	fault.name Matches "UnresolvedVariable"
semanticcachelookup.POLICY_NAME.failed	POLICY_NAME é o nome especificado pelo usuário da política que causou a falha.	semanticcachelookup.SC-lookup.failed = true

Exemplo de resposta de erro

Observação: para tratamento de erros, a prática recomendada é interceptar a parte errorcode da resposta de erro. Não confie no texto do faultstring, porque ele pode mudar.

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

Exemplo de regra de falha

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

Esquemas

Cada tipo de política é definido por um esquema XML (.xsd). Para referência, os esquemas de política estão disponíveis no GitHub.