Modelos de base de consulta e modelos externos

Neste artigo, você aprenderá a formatar solicitações de consulta para modelos básicos e modelos externos e enviá-las para seu ponto de extremidade de serviço de modelo.

Para solicitações de consulta de modelos tradicionais de ML ou Python, consulte Pontos de extremidade de serviço de consulta para modelos personalizados.

O Mosaic AI Model Serving suporta APIs de modelos de base e modelos externos para acessar modelos de IA generativos. O Model Serving usa uma API e SDK unificadas compatíveis com OpenAI para consultá-los. Isso torna possível experimentar e personalizar modelos de IA generativa para produção em nuvens e provedores suportados.

O Mosaic AI Model Serving fornece as seguintes opções para enviar solicitações de pontuação para pontos de extremidade que servem modelos de base ou modelos externos:

Método	Detalhes
Cliente OpenAI	Consulte um modelo hospedado por um ponto de extremidade Mosaic AI Model Serving usando o cliente OpenAI. Especifique o modelo que serve o nome do ponto de extremidade como a model entrada. Suportado para modelos de chat, incorporações e conclusão disponibilizados por APIs de Modelo de Base ou modelos externos.
Servindo a interface do usuário	Selecione Consultar ponto de extremidade na página Ponto de extremidade de serviço. Insira os dados de entrada do modelo no formato JSON e clique em Enviar solicitação. Se o modelo tiver um exemplo de entrada registrado, use Mostrar exemplo para carregá-lo.
API REST	Chame e consulte o modelo usando a API REST. Consulte POST /serving-endpoints/{name}/invocations para obter detalhes. Para marcar solicitações para pontos de extremidade que atendem a vários modelos, consulte Consultar modelos individuais atrás de um ponto de extremidade.
SDK de implantações MLflow	Use a função predict() do MLflow Deployments SDK para consultar o modelo.
Databricks Python SDK	O Databricks Python SDK é uma camada sobre a API REST. Ele lida com detalhes de baixo nível, como autenticação, facilitando a interação com os modelos.
Função SQL	Invoque a inferência do modelo diretamente do SQL usando a ai_query função SQL. Consulte Consultar um modelo servido com ai_query().

Requerimentos

• Um modelo de ponto de extremidade de serviço.
• Um espaço de trabalho Databricks em uma região suportada.
  • Regiões de APIs do Modelo de Fundação
  • Regiões de modelos externos
• Para enviar uma solicitação de pontuação por meio do cliente OpenAI, API REST ou SDK de implantação MLflow, você deve ter um token de API Databricks.

Importante

Como prática recomendada de segurança para cenários de produção, o Databricks recomenda que você use tokens OAuth máquina a máquina para autenticação durante a produção.

Para teste e desenvolvimento, o Databricks recomenda o uso de um token de acesso pessoal pertencente a entidades de serviço em vez de usuários do espaço de trabalho. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

Instalar pacotes

Depois de selecionar um método de consulta, você deve primeiro instalar o pacote apropriado no cluster.

Cliente OpenAI

Para usar o cliente OpenAI, o databricks-sdk[openai] pacote precisa ser instalado em seu cluster. O SDK do Databricks fornece um wrapper para construir o cliente OpenAI com autorização configurada automaticamente para consultar modelos de base do Databricks. Execute o seguinte no seu bloco de notas ou no seu terminal local:

!pip install databricks-sdk[openai]

O seguinte só é necessário ao instalar o pacote em um Notebook Databricks

dbutils.library.restartPython()

API REST

O acesso à API REST de serviço está disponível no Databricks Runtime for Machine Learning.

SDK de implantações MLflow

!pip install mlflow

O seguinte só é necessário ao instalar o pacote em um Notebook Databricks

dbutils.library.restartPython()

Databricks Python SDK

O SDK do Databricks para Python já está instalado em todos os clusters do Azure Databricks que usam o Databricks Runtime 13.3 LTS ou superior. Para clusters do Azure Databricks que usam o Databricks Runtime 12.2 LTS e inferior, você deve instalar o SDK do Databricks para Python primeiro. Consulte Etapa 1: Instalar ou atualizar o SDK do Databricks para Python.

Consultar um modelo de conclusão de chat

Seguem-se exemplos para consultar um modelo de chat. O exemplo se aplica à consulta de um modelo de chat disponibilizado usando qualquer um dos recursos de Serviço de Modelo: APIs de Modelo de Base ou modelos externos.

Para obter um exemplo de inferência em lote, consulte Inferência em lote usando a taxa de transferência provisionada de APIs do Modelo de Base.

Cliente OpenAI

A seguir está uma solicitação de bate-papo para o modelo DBRX Instruct disponibilizado pelo ponto de extremidade de pagamento por token das APIs do Foundation Model, databricks-dbrx-instruct em seu espaço de trabalho. Para usar o cliente OpenAI, especifique o modelo que serve o nome do ponto de extremidade como entrada model .

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
openai_client = w.serving_endpoints.get_open_ai_client()

response = openai_client.chat.completions.create(
    model="databricks-dbrx-instruct",
    messages=[
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is a mixture of experts model?",
      }
    ],
    max_tokens=256
)

Para consultar modelos de base fora do seu espaço de trabalho, você deve usar o cliente OpenAI diretamente. Você também precisa de sua instância de espaço de trabalho Databricks para conectar o cliente OpenAI ao Databricks.O exemplo a seguir pressupõe que você tenha um token de API Databricks instalado openai em sua computação.

import os
import openai
from openai import OpenAI

client = OpenAI(
    api_key="dapi-your-databricks-token",
    base_url="https://example.staging.cloud.databricks.com/serving-endpoints"
)

response = client.chat.completions.create(
    model="databricks-dbrx-instruct",
    messages=[
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "What is a mixture of experts model?",
      }
    ],
    max_tokens=256
)

API REST

Importante

O exemplo a seguir usa parâmetros de API REST para consultar pontos de extremidade de serviço que servem modelos de base. Esses parâmetros são visualização pública e a definição pode mudar. Consulte POST /serving-endpoints/{name}/invocations.

A seguir está uma solicitação de bate-papo para o modelo DBRX Instruct disponibilizado pelo ponto de extremidade de pagamento por token das APIs do Foundation Model, databricks-dbrx-instruct em seu espaço de trabalho.

curl \
-u token:$DATABRICKS_TOKEN \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": " What is a mixture of experts model?"
    }
  ]
}' \
https://<workspace_host>.databricks.com/serving-endpoints/databricks-dbrx-instruct/invocations \

SDK de implantações MLflow

Importante

O exemplo a seguir usa a predict() API do MLflow Deployments SDK.

A seguir está uma solicitação de bate-papo para o modelo DBRX Instruct disponibilizado pelo ponto de extremidade de pagamento por token das APIs do Foundation Model, databricks-dbrx-instruct em seu espaço de trabalho.

import mlflow.deployments

# Only required when running this example outside of a Databricks Notebook
export DATABRICKS_HOST="https://<workspace_host>.databricks.com"
export DATABRICKS_TOKEN="dapi-your-databricks-token"

client = mlflow.deployments.get_deploy_client("databricks")

chat_response = client.predict(
    endpoint="databricks-dbrx-instruct",
    inputs={
        "messages": [
            {
              "role": "user",
              "content": "Hello!"
            },
            {
              "role": "assistant",
              "content": "Hello! How can I assist you today?"
            },
            {
              "role": "user",
              "content": "What is a mixture of experts model??"
            }
        ],
        "temperature": 0.1,
        "max_tokens": 20
    }
)

Databricks Python SDK

A seguir está uma solicitação de bate-papo para o modelo DBRX Instruct disponibilizado pelo ponto de extremidade de pagamento por token das APIs do Foundation Model, databricks-dbrx-instruct em seu espaço de trabalho.

Esse código deve ser executado em um bloco de anotações em seu espaço de trabalho. Consulte Usar o SDK do Databricks para Python de um bloco de anotações do Azure Databricks.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ChatMessage, ChatMessageRole

w = WorkspaceClient()
response = w.serving_endpoints.query(
    name="databricks-dbrx-instruct",
    messages=[
        ChatMessage(
            role=ChatMessageRole.SYSTEM, content="You are a helpful assistant."
        ),
        ChatMessage(
            role=ChatMessageRole.USER, content="What is a mixture of experts model?"
        ),
    ],
    max_tokens=128,
)
print(f"RESPONSE:\n{response.choices[0].message.content}")

LangChain

Para consultar um ponto de extremidade de modelo de base usando LangChain, você pode usar a classe ChatDatabricks ChatModel e especificar o endpoint.

O exemplo a seguir usa a ChatDatabricks classe ChatModel em LangChain para consultar o ponto de extremidade de pagamento por token das APIs do Modelo de Base, databricks-dbrx-instruct.

%pip install langchain-databricks

from langchain_core.messages import HumanMessage, SystemMessage
from langchain_databricks import ChatDatabricks

messages = [
    SystemMessage(content="You're a helpful assistant"),
    HumanMessage(content="What is a mixture of experts model?"),
]

llm = ChatDatabricks(endpoint_name="databricks-dbrx-instruct")
llm.invoke(messages)

SQL

Importante

O exemplo a seguir usa a função SQL interna, ai_query. Esta função é Public Preview e a definição pode mudar. Consulte Consultar um modelo servido com ai_query().

A seguir está uma solicitação de bate-papo disponibilizada llama-2-70b-chat pelo ponto de extremidade databricks-llama-2-70b-chat de pagamento por token das APIs do Modelo de Fundação em seu espaço de trabalho.

Nota

A ai_query() função não suporta pontos de extremidade de consulta que servem o modelo DBRX ou DBRX Instruct.

SELECT ai_query(
    "databricks-llama-2-70b-chat",
    "Can you explain AI in ten words?"
  )

Como exemplo, a seguir está o formato de solicitação esperado para um modelo de chat ao usar a API REST. Para modelos externos, você pode incluir parâmetros adicionais que são válidos para um determinado provedor e configuração de ponto final. Consulte Parâmetros de consulta adicionais.

{
  "messages": [
    {
      "role": "user",
      "content": "What is a mixture of experts model?"
    }
  ],
  "max_tokens": 100,
  "temperature": 0.1
}

A seguir está um formato de resposta esperado para uma solicitação feita usando a API REST:

{
  "model": "databricks-dbrx-instruct",
  "choices": [
    {
      "message": {},
      "index": 0,
      "finish_reason": null
    }
  ],
  "usage": {
    "prompt_tokens": 7,
    "completion_tokens": 74,
    "total_tokens": 81
  },
  "object": "chat.completion",
  "id": null,
  "created": 1698824353
}

Consultar um modelo de incorporação

A seguir está uma solicitação de incorporação para o bge-large-en modelo disponibilizado pelas APIs do Foundation Model. O exemplo se aplica à consulta de um modelo de incorporação disponibilizado usando qualquer um dos recursos de Serviço de Modelo: APIs de Modelo de Base ou modelos externos.

Cliente OpenAI

Para usar o cliente OpenAI, especifique o modelo que serve o nome do ponto de extremidade como entrada model .

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
openai_client = w.serving_endpoints.get_open_ai_client()

response = openai_client.embeddings.create(
  model="databricks-bge-large-en",
  input="what is databricks"
)

Para consultar modelos de base fora do seu espaço de trabalho, você deve usar o cliente OpenAI diretamente. O exemplo a seguir pressupõe que você tenha um token de API Databricks instalado openai em sua computação. Você também precisa da instância do espaço de trabalho Databricks para conectar o cliente OpenAI ao Databricks.

import os
import openai
from openai import OpenAI

client = OpenAI(
    api_key="dapi-your-databricks-token",
    base_url="https://example.staging.cloud.databricks.com/serving-endpoints"
)

response = client.embeddings.create(
  model="databricks-bge-large-en",
  input="what is databricks"
)

API REST

Importante

O exemplo a seguir usa parâmetros de API REST para consultar pontos de extremidade de serviço que servem modelos de base ou modelos externos. Esses parâmetros são visualização pública e a definição pode mudar. Consulte POST /serving-endpoints/{name}/invocations.

curl \
-u token:$DATABRICKS_TOKEN \
-X POST \
-H "Content-Type: application/json" \
-d  '{ "input": "Embed this sentence!"}' \
https://<workspace_host>.databricks.com/serving-endpoints/databricks-bge-large-en/invocations

SDK de implantações MLflow

Importante

O exemplo a seguir usa a predict() API do MLflow Deployments SDK.

import mlflow.deployments

export DATABRICKS_HOST="https://<workspace_host>.databricks.com"
export DATABRICKS_TOKEN="dapi-your-databricks-token"

client = mlflow.deployments.get_deploy_client("databricks")

embeddings_response = client.predict(
    endpoint="databricks-bge-large-en",
    inputs={
        "input": "Here is some text to embed"
    }
)

Databricks Python SDK

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ChatMessage, ChatMessageRole

w = WorkspaceClient()
response = w.serving_endpoints.query(
    name="databricks-bge-large-en",
    input="Embed this sentence!"
)
print(response.data[0].embedding)

LangChain

Para usar um modelo de APIs do Databricks Foundation Model em LangChain como um modelo de incorporação, importe a DatabricksEmbeddings classe e especifique o endpoint parâmetro da seguinte maneira:

%pip install langchain-databricks

from langchain_databricks import DatabricksEmbeddings

embeddings = DatabricksEmbeddings(endpoint="databricks-bge-large-en")
embeddings.embed_query("Can you explain AI in ten words?")

SQL

Importante

O exemplo a seguir usa a função SQL interna, ai_query. Esta função é Public Preview e a definição pode mudar. Consulte Consultar um modelo servido com ai_query().

SELECT ai_query(
    "databricks-bge-large-en",
    "Can you explain AI in ten words?"
  )

A seguir está o formato de solicitação esperado para um modelo de incorporação. Para modelos externos, você pode incluir parâmetros adicionais que são válidos para um determinado provedor e configuração de ponto final. Consulte Parâmetros de consulta adicionais.

{
  "input": [
    "embedding text"
  ]
}

O seguinte é o formato de resposta esperado:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": []
    }
  ],
  "model": "text-embedding-ada-002-v2",
  "usage": {
    "prompt_tokens": 2,
    "total_tokens": 2
  }
}

Verifique se as incorporações estão normalizadas

Use o seguinte para verificar se as incorporações geradas pelo seu modelo estão normalizadas.

import numpy as np

def is_normalized(vector: list[float], tol=1e-3) -> bool:
    magnitude = np.linalg.norm(vector)
    return abs(magnitude - 1) < tol

Consultar um modelo de conclusão de texto

Cliente OpenAI

Importante

Não há suporte para a consulta de modelos de conclusão de texto disponibilizados usando APIs de modelo de base pay-per-token usando o cliente OpenAI. Somente a consulta de modelos externos usando o cliente OpenAI é suportada, conforme demonstrado nesta seção.

O exemplo a seguir consulta o claude-2 modelo de conclusão hospedado pela Anthropic usando o cliente OpenAI. Para usar o cliente OpenAI, preencha o model campo com o nome do ponto de extremidade de serviço do modelo que hospeda o modelo que você deseja consultar.

Este exemplo usa um ponto de extremidade criado anteriormente, anthropic-completions-endpoint, configurado para acessar modelos externos do provedor de modelo antrópico. Veja como criar pontos de extremidade de modelo externos.

Consulte Modelos suportados para obter modelos adicionais que você pode consultar e seus provedores.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
openai_client = w.serving_endpoints.get_open_ai_client()

completion = openai_client.completions.create(
  model="anthropic-completions-endpoint",
  prompt="what is databricks",
  temperature=1.0
)
print(completion)

API REST

A seguir está uma solicitação de conclusão para consultar um modelo de conclusão disponibilizado usando modelos externos.

Importante

O exemplo a seguir usa parâmetros de API REST para consultar pontos de extremidade de serviço que servem modelos externos. Esses parâmetros são visualização pública e a definição pode mudar. Consulte POST /serving-endpoints/{name}/invocations.

curl \
 -u token:$DATABRICKS_TOKEN \
 -X POST \
 -H "Content-Type: application/json" \
 -d '{"prompt": "What is a quoll?", "max_tokens": 64}' \
https://<workspace_host>.databricks.com/serving-endpoints/<completions-model-endpoint>/invocations

SDK de implantações MLflow

A seguir está uma solicitação de conclusão para consultar um modelo de conclusão disponibilizado usando modelos externos.

Importante

O exemplo a seguir usa a predict() API do MLflow Deployments SDK.

import os
import mlflow.deployments

# Only required when running this example outside of a Databricks Notebook

os.environ['DATABRICKS_HOST'] = "https://<workspace_host>.databricks.com"
os.environ['DATABRICKS_TOKEN'] = "dapi-your-databricks-token"

client = mlflow.deployments.get_deploy_client("databricks")

completions_response = client.predict(
    endpoint="<completions-model-endpoint>",
    inputs={
        "prompt": "What is the capital of France?",
        "temperature": 0.1,
        "max_tokens": 10,
        "n": 2
    }
)

# Print the response
print(completions_response)

Databricks Python SDK

A seguir está uma solicitação de conclusão para consultar um modelo de conclusão disponibilizado usando modelos externos.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ChatMessage, ChatMessageRole

w = WorkspaceClient()
response = w.serving_endpoints.query(
    name="<completions-model-endpoint>",
    prompt="Write 3 reasons why you should train an AI model on domain specific data sets."
)
print(response.choices[0].text)

SQL

A seguir está uma solicitação de conclusão para consultar um modelo de conclusão disponibilizado usando modelos externos.

Importante

O exemplo a seguir usa a função SQL interna, ai_query. Esta função é Public Preview e a definição pode mudar. Consulte Consultar um modelo servido com ai_query().

SELECT ai_query(
    "text-completion",
    "Can you explain AI in ten words?"
  )

A seguir está o formato de solicitação esperado para um modelo de conclusão. Para modelos externos, você pode incluir parâmetros adicionais que são válidos para um determinado provedor e configuração de ponto final. Consulte Parâmetros de consulta adicionais.

{
  "prompt": "What is mlflow?",
  "max_tokens": 100,
  "temperature": 0.1,
  "stop": [
    "Human:"
  ],
  "n": 1,
  "stream": false,
  "extra_params":
  {
    "top_p": 0.9
  }
}

O seguinte é o formato de resposta esperado:

{
  "id": "cmpl-8FwDGc22M13XMnRuessZ15dG622BH",
  "object": "text_completion",
  "created": 1698809382,
  "model": "gpt-3.5-turbo-instruct",
  "choices": [
    {
    "text": "MLflow is an open-source platform for managing the end-to-end machine learning lifecycle. It provides tools for tracking experiments, managing and deploying models, and collaborating on projects. MLflow also supports various machine learning frameworks and languages, making it easier to work with different tools and environments. It is designed to help data scientists and machine learning engineers streamline their workflows and improve the reproducibility and scalability of their models.",
    "index": 0,
    "logprobs": null,
    "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 83,
    "total_tokens": 88
  }
}

Converse com LLMs suportados usando o AI Playground

Você pode interagir com modelos de linguagem grandes suportados usando o AI Playground. O AI Playground é um ambiente semelhante a um bate-papo onde você pode testar, solicitar e comparar LLMs do seu espaço de trabalho do Azure Databricks.

Recursos adicionais

• Tabelas de inferência para monitoramento e depuração de modelos
• Inferência em lote usando a taxa de transferência provisionada de APIs do Modelo de Base
• APIs do Modelo de fundação do Databricks
• Modelos externos no Mosaic AI Model Serving
• Modelos suportados para pagamento por token
• Referência da API REST do modelo de base