API Reasoning Engine

A API Reasoning Engine oferece o ambiente de execução gerenciado para fluxos de trabalho agentes personalizados em aplicativos de IA generativa. É possível criar um aplicativo usando frameworks de orquestração, como LangChain, e implantá-lo com o Reasoning Engine. Esse serviço tem todos os benefícios de segurança, privacidade, observabilidade e escalonabilidade da integração da Vertex AI.

Para mais informações conceituais sobre o Reasoning Engine, consulte Implantar o aplicativo.

Limitações

  • A API Reasoning Engine oferece suporte apenas a frameworks de orquestração em Python.
  • A API Reasoning Engine só tem suporte na região us-central1.

Exemplo de sintaxe

Sintaxe para criar e registrar um recurso de mecanismo de raciocínio.

Python

class SimpleAdditionApp:
    def query() -> str:
        """
           ...

        """

        return
...

reasoning_engine = reasoning_engines.ReasoningEngine.create(
    SimpleAdditionApp(),
    display_name="",
    description="",
    requirements=[...],
    extra_packages=[...],
)

Lista de parâmetros

Parâmetros
display_name

Obrigatório: string

ReasoningEngine: o nome de exibição do .
description

Opcional: string

A descrição do ReasoningEngine.
spec

Obrigatório: ReasoningEngineSpec

Configurações do ReasoningEngine.
package_spec

Obrigatório: PackageSpec

Uma especificação do pacote fornecida pelo usuário, como objetos em conserva e requisitos de pacote.
class_methods

Opcional: protobuf.Struct

Declarações para métodos de classe de objeto.

PackageSpec

PackageSpec contém a referência ao URI do Cloud Storage que armazena o arquivo YAML da OpenAPI.

Parâmetros
pickle_object_gcs_uri

Opcional: string

O URI do Cloud Storage do objeto Python armazenado.
dependency_files_gcs_uri

Opcional: string

O URI do Cloud Storage dos arquivos de dependência com a extensão tar.gz.
requirements_gcs_uri

Opcional: string

O URI do Cloud Storage do arquivo requirements.txt.
python_version

Opcional: string

A versão do Python. As versões com suporte incluem Python 3.8, 3.9, 3.10 e 3.11. Se não for especificado, o valor padrão será 3.10.

QueryReasoningEngine

Parâmetros
input

protobuf.struct

Os argumentos dentro de input precisam ser consistentes com o método de classe query definido na etapa de criação.

Exemplos

Implantar uma configuração básica de app

O exemplo a seguir usa um aplicativo que adiciona dois números inteiros e um aplicativo remoto com o Reasoning Engine:

SDK da Vertex AI para Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# staging_bucket = "gs://YOUR_BUCKET_NAME"
vertexai.init(
    project=PROJECT_ID, location="us-central1", staging_bucket=staging_bucket
)

class SimpleAdditionApp:
    def query(self, a: int, b: int) -> str:
        """Query the application.
        Args:
            a: The first input number
            b: The second input number
        Returns:
            int: The additional result.
        """
        return f"{int(a)} + {int(b)} is {int(a + b)}"

# Locally test
app = SimpleAdditionApp()
app.query(a=1, b=2)

# Create a remote app with Reasoning Engine.
# This may take 1-2 minutes to finish.
reasoning_engine = reasoning_engines.ReasoningEngine.create(
    SimpleAdditionApp(),
    display_name="Demo Addition App",
    description="A simple demo addition app",
    requirements=["cloudpickle==3"],
    extra_packages=[],
)
# Example response:
# Using bucket YOUR_BUCKET_NAME
# Writing to gs://YOUR_BUCKET_NAME/reasoning_engine/reasoning_engine.pkl
# ...
# ReasoningEngine created. Resource name: projects/123456789/locations/us-central1/reasoningEngines/123456
# To use this ReasoningEngine in another session:
# reasoning_engine = vertexai.preview.reasoning_engines.ReasoningEngine('projects/123456789/locations/...

Implantar uma configuração avançada de app

Este é um exemplo avançado que usa a cadeia de LangChain, modelos de prompt e a API Gemini:

SDK da Vertex AI para Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 


from typing import List

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# staging_bucket = "gs://YOUR_BUCKET_NAME"

vertexai.init(
    project=PROJECT_ID, location="us-central1", staging_bucket=staging_bucket
)

class LangchainApp:
    def __init__(self, project: str, location: str) -> None:
        self.project_id = project
        self.location = location

    def set_up(self) -> None:
        from langchain_core.prompts import ChatPromptTemplate
        from langchain_google_vertexai import ChatVertexAI

        system = (
            "You are a helpful assistant that answers questions "
            "about Google Cloud."
        )
        human = "{text}"
        prompt = ChatPromptTemplate.from_messages(
            [("system", system), ("human", human)]
        )
        chat = ChatVertexAI(project=self.project_id, location=self.location)
        self.chain = prompt | chat

    def query(self, question: str) -> Union[str, List[Union[str, Dict]]]:
        """Query the application.
        Args:
            question: The user prompt.
        Returns:
            str: The LLM response.
        """
        return self.chain.invoke({"text": question}).content

# Locally test
app = LangchainApp(project=PROJECT_ID, location="us-central1")
app.set_up()
print(app.query("What is Vertex AI?"))

# Create a remote app with Reasoning Engine
# Deployment of the app should take a few minutes to complete.
reasoning_engine = reasoning_engines.ReasoningEngine.create(
    LangchainApp(project=PROJECT_ID, location="us-central1"),
    requirements=[
        "google-cloud-aiplatform[langchain,reasoningengine]",
        "cloudpickle==3.0.0",
        "pydantic==2.7.4",
    ],
    display_name="Demo LangChain App",
    description="This is a simple LangChain app.",
    # sys_version="3.10",  # Optional
    extra_packages=[],
)
# Example response:
# Model_name will become a required arg for VertexAIEmbeddings starting...
# ...
# Create ReasoningEngine backing LRO: projects/123456789/locations/us-central1/reasoningEngines/...
# ReasoningEngine created. Resource name: projects/123456789/locations/us-central1/reasoningEngines/...
# ...

Mecanismo de raciocínio de consulta

Consultar um mecanismo de raciocínio

Neste exemplo, usamos a classe SimpleAdditionApp do exemplo de configuração básica de app.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação. Precisa ser us-central1.
  • REASONING_ENGINE_ID: o ID do mecanismo de raciocínio.
  • INPUT: protobuf.struct: os argumentos dentro de input precisam corresponder aos argumentos dentro do método def query(self, question: str) definido em Implantar uma configuração básica de app.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:query

Corpo JSON da solicitação:

{
  "input": {
    INPUT
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:query"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID:query" | Select-Object -Expand Content

SDK da Vertex AI para Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# reasoning_engine_id = "1234567890123456"
vertexai.init(project=PROJECT_ID, location="us-central1")
reasoning_engine = reasoning_engines.ReasoningEngine(reasoning_engine_id)

# Replace with kwargs for `.query()` method.
response = reasoning_engine.query(a=1, b=2)
print(response)
# Example response:
# 1 + 2 is 3

Listar mecanismos de raciocínio

Listar os mecanismos de raciocínio em um projeto.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação. Precisa ser us-central1.

Método HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines"

PowerShell

Execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines" | Select-Object -Expand Content

SDK da Vertex AI para Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

reasoning_engine_list = reasoning_engines.ReasoningEngine.list()
print(reasoning_engine_list)
# Example response:
# [<vertexai.reasoning_engines._reasoning_engines.ReasoningEngine object at 0x71a0e5cb99c0>
# resource name: projects/123456789/locations/us-central1/reasoningEngines/111111111111111111,
# <vertexai.reasoning_engines._reasoning_engines.ReasoningEngine object at 0x71a0e5cbac80>
# resource name: projects/123456789/locations/us-central1/reasoningEngines/222222222222222222]

Acessar mecanismo de raciocínio

Conseguir detalhes de um mecanismo de raciocínio.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação. Precisa ser us-central1.
  • REASONING_ENGINE_ID: o ID do mecanismo de raciocínio.

Método HTTP e URL: 

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID"

PowerShell

Execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID" | Select-Object -Expand Content

SDK da Vertex AI para Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# reasoning_engine_id = "1234567890123456"
vertexai.init(project=PROJECT_ID, location="us-central1")

reasoning_engine = reasoning_engines.ReasoningEngine(reasoning_engine_id)
print(reasoning_engine)
# Example response:
# <vertexai.reasoning_engines._reasoning_engines.ReasoningEngine object at 0x757999a63c40>
# resource name: projects/[PROJECT_ID]/locations/us-central1/reasoningEngines/1234567890123456

Excluir mecanismo de raciocínio

Excluir um mecanismo de raciocínio.

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • LOCATION: a região para processar a solicitação. Precisa ser us-central1.
  • REASONING_ENGINE_ID: o ID do mecanismo de raciocínio.

Método HTTP e URL: 

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID

Para enviar a solicitação, escolha uma destas opções:

curl

execute o seguinte comando: 

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID"

PowerShell

Execute o seguinte comando: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/REASONING_ENGINE_ID" | Select-Object -Expand Content

SDK da Vertex AI para Python

Para saber como instalar o SDK da Vertex AI para Python, consulte Instalar o SDK da Vertex AI para Python. Saiba mais na documentação de referência da API SDK da Vertex AI para Python. 

import vertexai
from vertexai.preview import reasoning_engines

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# reasoning_engine_id = "1234567890123456"
vertexai.init(project=PROJECT_ID, location="us-central1")

reasoning_engine = reasoning_engines.ReasoningEngine(reasoning_engine_id)
reasoning_engine.delete()
# Example response:
# Deleting ReasoningEngine:projects/[PROJECT_ID]/locations/us-central1/reasoningEngines/1234567890123456
# ...
# ... resource projects/[PROJECT_ID]/locations/us-central1/reasoningEngines/1234567890123456 deleted.

A seguir