Cortex Analyst¶
Visão geral¶
Cortex Analyst é um recurso de LLM do Snowflake Cortex totalmente gerenciado e habilitado que ajuda você a criar aplicativos capazes de responder de forma confiável a perguntas de negócios com base em seus dados estruturados no Snowflake. Com o Cortex Analyst, os usuários empresariais podem fazer perguntas em linguagem natural e receber respostas diretas sem escrever SQL. Disponível como um REST API prático, Cortex Analyst pode ser perfeitamente integrado em qualquer aplicativo.
Criar uma solução de análise de autoatendimento conversacional de nível de produção requer um serviço que gere respostas SQL de texto precisas. Para a maioria das equipes, desenvolver um serviço que equilibre com sucesso precisão, latência e custos é uma tarefa assustadora. O Cortex Analyst simplifica esse processo ao fornecer um sistema de AI de agente sofisticado e totalmente gerenciado que lida com todas essas complexidades, gerando respostas SQL de texto altamente precisas. Ele ajuda você a acelerar a entrega de análise conversacionais de alta precisão e autoatendimento para equipes de negócios, evitando perdas de tempo, como padrões de soluções RAG complexos, experimentação de modelo e planejamento de capacidade de GPU. As consultas SQL geradas são executadas no mecanismo escalável Snowflake, garantindo desempenho de preço líder do setor e menor custo total de propriedade (TCO).
Dica
Quer começar a usar o Cortex Analyst rapidamente? Experimente o tutorial Tutorial: Responda a perguntas sobre dados de receita de séries temporais com o Cortex Analyst.
Principais recursos¶
Análises de autoatendimento por meio de consultas em linguagem natural. Encante suas equipes de negócios e usuários não técnicos com respostas instantâneas e insights de seus dados estruturados no Snowflake. Usando o Cortex Analyst, você pode criar aplicativos de bate-papo downstream que permitem que seus usuários façam perguntas usando linguagem natural e recebam respostas precisas rapidamente.
REST API conveniente para integração em fluxos de trabalho empresariais existentes. Cortex Analyst adota uma abordagem de primeiro API, dando a você controle total sobre a experiência do usuário final. Integre facilmente o Cortex Analyst às ferramentas e plataformas de negócios existentes, levando o poder dos insights de dados para onde os usuários de negócios já operam, como aplicativos Streamlit, Slack, Teams, interfaces de bate-papo personalizadas e muito mais.
Desenvolvido com modelos de linguagem de última geração: Por padrão, Cortex Analyst é desenvolvido com os modelos mais recentes Meta Llama e Mistral, que são executados com segurança dentro do Snowflake Cortex, o serviço de AI inteligente e totalmente gerenciado da Snowflake. Opcionalmente, você também pode dar acesso ao Cortex Analyst aos modelos mais recentes de OpenAI GPT hospedados no Azure. Em tempo de execução, Cortex Analyst seleciona a melhor combinação de modelos para garantir a mais alta precisão e desempenho para cada consulta. Para obter mais detalhes, consulte Habilitação do uso de modelos do Azure OpenAI. À medida que LLMs evoluem, a Snowflake continuará explorando a adição de mais modelos à mistura para melhorar ainda mais o desempenho e a precisão.
Modelo semântico para alta precisão e exatidão: soluções de AI genéricas geralmente têm dificuldades com conversões de texto para SQL quando recebem apenas um esquema de banco de dados, pois os esquemas não têm conhecimento crítico, como definições de processos de negócios e tratamento de métricas. O Cortex Analyst supera essa limite usando um modelo semântico que preenche a lacuna entre usuários de negócios e bancos de dados. Capturados em um arquivo YAML leve, a estrutura geral e os conceitos do modelo semântico são semelhantes aos dos esquemas de banco de dados, mas permitem uma descrição mais rica das informações semânticas em torno dos dados.
Segurança e governança. A base de privacidade em primeiro lugar e a segurança de nível empresarial da Snowflake garantem que você possa explorar casos de uso orientados a AI com confiança, sabendo que seus dados estão protegidos pelos mais altos padrões de privacidade e governança.
Cortex Analyst não faz treinamento em dados do cliente. Não usamos seus Dados do Cliente para treinar ou ajustar qualquer modelo a ser disponibilizado para uso em nossa base de clientes. Além disso, para inferência, Cortex Analyst utiliza os metadados fornecidos no arquivo YAML de modelo semântico (por exemplo, nomes de tabela, nomes de colunas, tipo de valor, descrições etc.) apenas para geração de consulta SQL. Essa consulta SQL é então executada no seu warehouse virtual Snowflake para gerar a saída final.
Os dados permanecem dentro dos limites de governança da Snowflake. Por padrão, Cortex Analyst é alimentado por LLMs hospedados do Snowflake da Mistral e Meta, garantindo que nenhum dados, incluindo metadados ou prompts, saia dos limites de governança do Snowflake. Se você optar por usar modelos OpenAI do Azure, somente metadados e prompts serão transmitidos fora do limite de governança do Snowflake.
Integração perfeita com os recursos de privacidade e governança do Snowflake. Cortex Analyst integra-se totalmente com as políticas de controle de acesso baseadas em funções (RBAC) do Snowflake, garantindo que as consultas SQL geradas e executadas estejam de acordo com todos os controles de acesso estabelecidos. Isso garante segurança e governança robustas para seus dados.
Requisitos de controle de acesso¶
Para usar Cortex Analyst com um modelo semântico, você precisa dos seguintes privilégios:
Privilégio |
Objeto |
|---|---|
USAGE |
Estágio que contém o arquivo YAML do modelo semântico, se o modelo semântico for carregado em um estágio. |
SELECT |
As tabelas definidas no modelo semântico. |
As solicitações ao Cortex Analyst API devem incluir informações de autenticação. O exemplo neste tópico usa um token de sessão para autenticação em uma conta Snowflake.
Disponibilidade de região¶
Cortex Analyst está disponível nativamente nas seguintes regiões.
AWS ap-northeast-1 (Tokyo)
AWS ap-southeast-2 (Sydney)
AWS us-east-1 (Virginia)
AWS us-west-2 (Oregon)
AWS eu-central-1 (Frankfurt)
AWS eu-west-1 (Ireland)
Azure East US 2 (Virginia)
Azure West Europe (Netherlands)
Se sua conta Snowflake estiver em uma região de nuvem diferente, você ainda poderá usar Cortex Analyst aproveitando o Inferência entre regiões. Depois que a inferência entre regiões estiver habilitada, Cortex Analyst processa solicitações em outras regiões para modelos que não estão disponíveis na sua região padrão. Para um desempenho ideal, faça a configuração entre regiões com regiões AWS US.
Nota
Se você optar por usar os modelos OpenAI do Azure, Cortex Analyst estará disponível para uso em todas as regiões AWS, Azure e GCP, exceto implantações Gov e VPS.
Problemas e limitações conhecidos¶
Se você carregar um arquivo YAML de modelo semântico em um estágio, o acesso a esse modelo semântico será controlado pelo acesso ao estágio em que ele foi carregado. Isso significa que qualquer função com acesso ao estágio pode acessar os modelos semânticos naquele estágio, mesmo que a função não tenha acesso às tabelas subjacente.
Junções não são diretamente suportadas no modelo semântico. Em vez disso, use exibições que contenham dados pré-unidos.
Por padrão, Cortex Analyst tem uma taxa limitada a 20 solicitações por minuto, o que deve ser suficiente para prova de conceito. Entre em contato com seu engenheiro de vendas para solicitação um limite maior.
Habilitação do uso de modelos do Azure OpenAI¶
Por padrão, Cortex Analyst é alimentado por LLMs do Cortex hospedados pela Snowflake. No entanto, você pode optar explicitamente por permitir que o Cortex Analyst use dos modelos OpenAIGPT mais recentes, hospedados pelo Microsoft Azure, juntamente com os modelos hospedados pelo Snowflake. Em tempo de execução, Cortex Analyst seleciona a combinação ideal de modelos para garantir a mais alta precisão e desempenho para cada consulta.
Você pode configurar sua conta para permitir o uso dos modelos OpenAI GPT do Azure com o parâmetroENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI. Por padrão, o parâmetro está desabilitado e só pode ser definir pela função ACCOUNTADMIN usando o comando ALTER ACCOUNT:
USE ROLE ACCOUNTADMIN;
ALTER ACCOUNT SET ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI = TRUE;
Dica
Para ver o valor atual deste parâmetro, use a seguinte instrução SQL.
SHOW PARAMETERS LIKE 'ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI' IN ACCOUNT
Consulte ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI para obter mais detalhes.
Quando este parâmetro estiver habilitado, Cortex Analyst poderá ser alimentado por qualquer combinação de:
Modelos hospedados pela Snowflake, atualmente modelos Mistral Large e Llama3
Modelos OpenAI do Azure, atualmente GPT-4o (requer aceitação explícita)
Nota
Cortex Analyst pode usar modelos diferentes no futuro para melhorar ainda mais o desempenho e a precisão.
Considerações¶
Arquivos de modelo semântico são classificados como metadados. Se você optar por usar modelos OpenAI do Azure no Cortex Analyst, seu modelo semântico será processado pelo Microsoft Azure, um terceiro. No entanto, os Dados do Cliente não são compartilhados nem processados pelo Azure.
ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI¶
O parâmetro de conta ENABLE_CORTEX_ANALYST_MODEL_AZURE_OPENAI, se TRUE, permite que o Cortex Analyst use os modelos OpenAI do Azure.
Tipo de parâmetro |
Sessão |
|---|---|
Tipo de dados |
BOOLEAN |
Descrição |
Controla se o Cortex Analyst pode usar modelos OpenAI do Azure para processar solicitações. |
Valores |
|
Padrão |
FALSE |
Exemplo de Cortex Analyst¶
Siga estas etapas para criar um Streamlit interativo no Snowflake (SiS) ou um aplicativo Streamlit independente que usa Cortex Analyst.
Criar e executar um Streamlit no app Snowflake
Criar um modelo semântico¶
Um modelo semântico é um mecanismo leve que aborda questões relacionadas à diferença de linguagem entre usuários empresariais e definições de banco de dados, permitindo a especificação de detalhes semânticos adicionais sobre um conjunto de dados. Esses detalhes semânticos adicionais, como nomes mais descritivos ou sinônimos, permitem ao Cortex Analyst responder a perguntas de dados de forma muito mais confiável.
Comece com uma lista de perguntas que você gostaria que o Cortex Analyst respondesse. Com base nisso, decida o conjunto de dados para seu modelo semântico.
Crie seu modelo semântico com base em YAML na especificação. Para sua conveniência, experimente o Gerador de modelo semântico. Além disso, não deixe de revisar as dicas para criar um modelo semântico.
Carregar modelo semântico¶
Você pode carregar um arquivo YAML de modelo semântico para um estágio ou passar o modelo semântico YAML como uma cadeia de caracteres no corpo da solicitação. Se você carregar um YAML de modelo semântico em um estágio, o acesso a esse modelo semântico será controlado pelo acesso ao estágio em que ele foi carregado. Isso significa que qualquer função com acesso ao estágio pode acessar os modelos semânticos naquele estágio, mesmo que a função não tenha acesso às tabelas nas quais os modelos são baseados. Garanta que as funções com acesso concedido a um estágio tenham acesso SELECT a todas as tabelas referenciadas em todos os modelos semânticos naquele estágio.
Abaixo está um exemplo de como definir os estágios contendo os modelos semânticos. Um estágio (public) é acessível a todos os membros da organização, enquanto outro estágio (sales) é acessível apenas à função sales_analyst.
Crie o banco de dados e o esquema para o estágio. O exemplo a seguir cria um banco de dados chamado semantic_model com um esquema chamado definition, mas você pode usar qualquer cadeia de caracteres de identificador válida para esses nomes.
CREATE DATABASE semantic_model;
CREATE SCHEMA semantic_model.definitions;
GRANT USAGE ON DATABASE semantic_model TO ROLE PUBLIC;
GRANT USAGE ON SCHEMA semantic_model.definitions TO ROLE PUBLIC;
USE SCHEMA semantic_model.definitions;
Em seguida, crie os estágios para armazenar seus modelos semânticos:
CREATE STAGE public DIRECTORY = (ENABLE = TRUE);
GRANT READ ON STAGE public TO ROLE PUBLIC;
CREATE STAGE sales DIRECTORY = (ENABLE = TRUE);
GRANT READ ON STAGE sales TO ROLE sales_analyst;
Se estiver usando o Snowsight, você pode atualizar a página e encontrar os estágios recém-criados no explorador de objeto de banco de dados. Você pode abrir a página do estágio em uma nova guia e carregar seus arquivos YAML no Snowsight.
Como alternativa, você pode usar o cliente Snowflake CLI para fazer upload do seu sistema de arquivo local.
snow stage copy file:///path/to/local/file.yaml @sales
Criação de um Streamlit no aplicativo Snowflake¶
Este exemplo mostra como criar um Streamlit no aplicativo Snowflake que recebe uma pergunta em linguagem natural como entrada e chama Cortex Analyst para gerar uma resposta com base no modelo semântico fornecido.
Para obter mais informações sobre como criar e executar aplicativos Streamlit no Snowflake, consulte Sobre a Streamlit in Snowflake.
Siga as instruções em Criação de um aplicativo Streamlit usando Snowsight para criar um novo aplicativo Streamlit no Snowsight.
Copie o código Streamlit abaixo no editor de código.
Substitua os valores do espaço reservado pelos detalhes da sua conta.
Para versão preliminar do aplicativo, selecione Run para atualizar o conteúdo no painel de versão preliminar do Streamlit.
from typing import Dict, List, Optional
import _snowflake
import json
import streamlit as st
import time
from snowflake.snowpark.context import get_active_session
DATABASE = "SNOWFLAKE_SEMANTIC_CONTEXT"
SCHEMA = "DEFINITIONS"
STAGE = "PUBLIC"
FILE = "revenue_timeseries.yaml"
def send_message(prompt: str) -> dict:
"""Calls the REST API and returns the response."""
request_body = {
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": prompt
}
]
}
],
"semantic_model_file": f"@{DATABASE}.{SCHEMA}.{STAGE}/{FILE}",
}
resp = _snowflake.send_snow_api_request(
"POST",
f"/api/v2/cortex/analyst/message",
{},
{},
request_body,
{},
30000,
)
if resp["status"] < 400:
return json.loads(resp["content"])
else:
st.session_state.messages.pop()
raise Exception(
f"Failed request with status {resp['status']}: {resp}"
)
def process_message(prompt: str) -> None:
"""Processes a message and adds the response to the chat."""
st.session_state.messages.append(
{"role": "user", "content": [{"type": "text", "text": prompt}]}
)
with st.chat_message("user"):
st.markdown(prompt)
with st.chat_message("assistant"):
with st.spinner("Generating response..."):
response = send_message(prompt=prompt)
request_id = response["request_id"]
content = response["message"]["content"]
st.session_state.messages.append(
{**response['message'], "request_id": request_id}
)
display_content(content=content, request_id=request_id) # type: ignore[arg-type]
def display_content(
content: List[Dict[str, str]],
request_id: Optional[str] = None,
message_index: Optional[int] = None,
) -> None:
"""Displays a content item for a message."""
message_index = message_index or len(st.session_state.messages)
if request_id:
with st.expander("Request ID", expanded=False):
st.markdown(request_id)
for item in content:
if item["type"] == "text":
st.markdown(item["text"])
elif item["type"] == "suggestions":
with st.expander("Suggestions", expanded=True):
for suggestion_index, suggestion in enumerate(item["suggestions"]):
if st.button(suggestion, key=f"{message_index}_{suggestion_index}"):
st.session_state.active_suggestion = suggestion
elif item["type"] == "sql":
display_sql(item["statement"])
@st.cache_data
def display_sql(sql: str) -> None:
with st.expander("SQL Query", expanded=False):
st.code(sql, language="sql")
with st.expander("Results", expanded=True):
with st.spinner("Running SQL..."):
session = get_active_session()
df = session.sql(sql).to_pandas()
if len(df.index) > 1:
data_tab, line_tab, bar_tab = st.tabs(
["Data", "Line Chart", "Bar Chart"]
)
data_tab.dataframe(df)
if len(df.columns) > 1:
df = df.set_index(df.columns[0])
with line_tab:
st.line_chart(df)
with bar_tab:
st.bar_chart(df)
else:
st.dataframe(df)
def show_conversation_history() -> None:
for message_index, message in enumerate(st.session_state.messages):
chat_role = "assistant" if message["role"] == "analyst" else "user"
with st.chat_message(chat_role):
display_content(
content=message["content"],
request_id=message.get("request_id"),
message_index=message_index,
)
def reset() -> None:
st.session_state.messages = []
st.session_state.suggestions = []
st.session_state.active_suggestion = None
st.title("Cortex analyst")
st.markdown(f"Semantic Model: `{FILE}`")
if "messages" not in st.session_state:
reset()
with st.sidebar:
if st.button("Reset conversation"):
reset()
show_conversation_history()
if user_input := st.chat_input("What is your question?"):
process_message(prompt=user_input)
if st.session_state.active_suggestion:
process_message(prompt=st.session_state.active_suggestion)
st.session_state.active_suggestion = None
Interagir com o aplicativo Streamlit¶
Navegue até o aplicativo Streamlit no seu navegador ou até o painel de versão preliminar do Streamlit no Snowflake.
Comece a fazer perguntas sobre seus dados em linguagem natural (por exemplo “Quais perguntas posso fazer?”).
Criação de um aplicativo Streamlit independente¶
Você também pode usar o código de exemplo acima para criar um aplicativo independente.
Instale o Streamlit.
Crie um arquivo Python localmente chamado
analyst_api.py.Copie o código Streamlit abaixo no arquivo.
Substitua os valores do espaço reservado pelos detalhes da sua conta.
Execute o aplicativo Streamlit usando
streamlit run analyst_api.py.
O banco de dados e o esquema especificados no código a seguir são o local do estágio para o arquivo YAML de modelo semântico. A função usada no conector Snowflake deve ter acesso aos dados subjacente definidos no modelo semântico.
from typing import Any, Dict, List, Optional
import pandas as pd
import requests
import snowflake.connector
import streamlit as st
HOST = "<host>"
DATABASE = "<database>"
SCHEMA = "<schema>"
STAGE = "<stage>"
FILE = "<file>"
if 'CONN' not in st.session_state or st.session_state.CONN is None:
st.session_state.CONN = snowflake.connector.connect(
user="<user>",
password="<password>",
account="<account>",
host=HOST,
port=443,
warehouse="<warehouse>",
role="<role>",
)
def send_message(prompt: str) -> Dict[str, Any]:
"""Calls the REST API and returns the response."""
request_body = {
"messages": [{"role": "user", "content": [{"type": "text", "text": prompt}]}],
"semantic_model_file": f"@{DATABASE}.{SCHEMA}.{STAGE}/{FILE}",
}
resp = requests.post(
url=f"https://{HOST}/api/v2/cortex/analyst/message",
json=request_body,
headers={
"Authorization": f'Snowflake Token="{st.session_state.CONN.rest.token}"',
"Content-Type": "application/json",
},
)
request_id = resp.headers.get("X-Snowflake-Request-Id")
if resp.status_code < 400:
return {**resp.json(), "request_id": request_id} # type: ignore[arg-type]
else:
st.session_state.messages.pop()
raise Exception(
f"Failed request (id: {request_id}) with status {resp.status_code}: {resp.text}"
)
def process_message(prompt: str) -> None:
"""Processes a message and adds the response to the chat."""
st.session_state.messages.append(
{"role": "user", "content": [{"type": "text", "text": prompt}]}
)
with st.chat_message("user"):
st.markdown(prompt)
with st.chat_message("assistant"):
with st.spinner("Generating response..."):
response = send_message(prompt=prompt)
request_id = response["request_id"]
content = response["message"]["content"]
st.session_state.messages.append(
{**response['message'], "request_id": request_id}
)
display_content(content=content, request_id=request_id) # type: ignore[arg-type]
def display_content(
content: List[Dict[str, str]],
request_id: Optional[str] = None,
message_index: Optional[int] = None,
) -> None:
"""Displays a content item for a message."""
message_index = message_index or len(st.session_state.messages)
if request_id:
with st.expander("Request ID", expanded=False):
st.markdown(request_id)
for item in content:
if item["type"] == "text":
st.markdown(item["text"])
elif item["type"] == "suggestions":
with st.expander("Suggestions", expanded=True):
for suggestion_index, suggestion in enumerate(item["suggestions"]):
if st.button(suggestion, key=f"{message_index}_{suggestion_index}"):
st.session_state.active_suggestion = suggestion
elif item["type"] == "sql":
display_sql(item["statement"])
@st.cache_data
def display_sql(sql: str) -> None:
with st.expander("SQL Query", expanded=False):
st.code(sql, language="sql")
with st.expander("Results", expanded=True):
with st.spinner("Running SQL..."):
df = pd.read_sql(sql, st.session_state.CONN)
if len(df.index) > 1:
data_tab, line_tab, bar_tab = st.tabs(
["Data", "Line Chart", "Bar Chart"]
)
data_tab.dataframe(df)
if len(df.columns) > 1:
df = df.set_index(df.columns[0])
with line_tab:
st.line_chart(df)
with bar_tab:
st.bar_chart(df)
else:
st.dataframe(df)
def show_conversation_history() -> None:
for message_index, message in enumerate(st.session_state.messages):
chat_role = "assistant" if message["role"] == "analyst" else "user"
with st.chat_message(chat_role):
display_content(
content=message["content"],
request_id=message.get("request_id"),
message_index=message_index,
)
def reset() -> None:
st.session_state.messages = []
st.session_state.suggestions = []
st.session_state.active_suggestion = None
st.title("Cortex analyst")
st.markdown(f"Semantic Model: `{FILE}`")
if "messages" not in st.session_state:
reset()
with st.sidebar:
if st.button("Reset conversation"):
reset()
show_conversation_history()
if user_input := st.chat_input("What is your question?"):
process_message(prompt=user_input)
if st.session_state.active_suggestion:
process_message(prompt=st.session_state.active_suggestion)
st.session_state.active_suggestion = None
Como desabilitar a funcionalidade Cortex Analyst¶
Se você não quiser que Cortex Analyst esteja disponível em sua conta, desabilite o recurso alterando o parâmetro ENABLE_CORTEX_ANALYST usando a função ACCOUNTADMIN:
USE ROLE ACCOUNTADMIN;
ALTER ACCOUNT SET ENABLE_CORTEX_ANALYST = FALSE;
Tipo de parâmetro |
Sessão |
|---|---|
Tipo de dados |
BOOLEAN |
Descrição |
Controla se a funcionalidade Cortex Analyst está habilitada na sua conta. |
Valores |
|
Padrão |
TRUE |
Considerações sobre custo¶
Cortex Analyst será gratuito até 15 de novembro de 2024. Detalhes sobre preço e faturamento estarão disponíveis em breve.
Avisos legais¶
Cortex Analyst é alimentado por tecnologia de machine learning, incluindo os modelos Llama 3 e Mistral Large da Meta. Os modelos base Llama 3 são licenciados sob a Licença Comunitária Llama 3 e os direitos autorais (c) Meta Platforms, Inc. Todos os direitos reservados. O uso deste recurso está sujeito à política de uso aceitável da Meta_.
A classificação dos dados de entradas e saídas é definido na tabela a seguir.
Classificação de dados de entrada |
Classificação de dados de saída |
Designação |
|---|---|---|
Usage Data |
Usage Data |
Preview AI Features [1] |
Para obter informações adicionais, consulte AI e ML Snowflake.