Comando AICOMMAND

Informações do conceito

Usando IA com análise de dados

Oferece suporte à análise de dados em linguagem natural ao integrar o Analytics com um serviço de IA externo.

Observação

Para usar o comando AICOMMAND,, você precisa instalar e configurar uma versão compatível do Python no computador em que o comando será executado. Também deve instalar duas bibliotecas Python: Pandas e API Python da OpenAI. Para obter mais informações, consulte Configuração do Python para uso com o Analytics.

O serviço externo de IA não é fornecido pela Diligent. Ele deve ser fornecido pela sua organização.

Conecte-se apenas a um serviço externo de IA que tenha sido aprovado para uso pela sua organização. Certifique-se de seguir todos os protocolos de segurança caso pretenda transmitir dados sensíveis do Analytics para o serviço de IA.

Os resultados da IA podem conter imprecisões ou erros. Utilize um método alternativo para verificar os resultados caso seja necessária precisão absoluta.

Sintaxe

AICOMMAND {<FIELDS> field <...n>|<FIELDS> ALL} <SCRIPT "path_and_filename"> TO table_name USER_PROMPT "user_prompt_text" <PASSWORD num> MODEL "model_information" URL "ai_service_api_url" <BATCHSIZE number_of_records> <IF test> <WHILE test> <FIRST range|NEXT range> <OPEN>

Parâmetros

Nome Descrição

FIELDS nome_campo <...n> | FIELDS ALL

Os campos ou expressões da tabela de origem do Analytics a serem enviados ao serviço de IA.

Você deve especificar pelo menos um campo ou expressão.

  • FIELDS nome_campoinclui o campo, os campos ou as expressões especificados.

    Separe nomes de campos com espaços. Os campos são exportados na ordem em que são listados.

    Para exportar um campo relacionado, o nome totalmente qualificado do campo deve ser especificado (nome_tabela.nome_campo). Por exemplo: Vendor.Vendor_Name

  • FIELDS ALLinclui todos os campos da tabela

    Os campos são exportados na ordem em que aparecem no layout da tabela. Os campos relacionados não são exportados.

Observação

Limite a quantidade total de dados enviados ao serviço de IA especificando apenas os campos estritamente necessários para o objetivo da sua análise.

Inclua um campo de identificador único se quiser unir ou relacionar a tabela retornada do serviço de IA com a tabela de origem original. Para obter mais informações, consulte Criar um campo de identificador exclusivo:.

SCRIPT "path_and_filename"

opcional

Se você usar seu próprio script Python com AICOMMAND, o caminho do arquivo e o nome do script.

Se você especificar um script, PASSWORD, MODEL e URL são opcionais. Para obter mais informações, consulte Usando seu próprio script Python.
TO nome_tabela

A localização para onde enviar os resultados do comando:

  • nome_tabelasalva os resultados em uma tabela do Analytics

    Especifique nome_tabela como uma cadeia entre aspas com uma extensão de arquivo .FIL. Por exemplo: TO "Output.FIL"

    Por padrão, o arquivo de dados da tabela (.FIL) é salvo na pasta que contém o projeto do Analytics.

    Use um caminho de arquivo absoluto ou relativo para salvar o arquivo de dados em uma pasta diferente já existente:

    • TO "C:\Output.FIL"
    • TO "Results\Output.FIL"

    Observação

    Os nomes de tabela são limitados a 64 caracteres alfanuméricos, sem contar a extensão .FIL. O nome pode incluir o caractere de sublinhado ( _ ) mas nenhum outro caractere especial e nenhum espaço. O nome não pode começar com um número.
USER_PROMPT "texto_do_prompt_do_usuario"

O texto do prompt a ser enviado ao serviço de IA.

O prompt informa ao serviço de IA como processar os dados de entrada que você envia e qual saída você deseja.

Observação

Você deve colocar texto_do_prompt_do_usuario entre aspas duplas ( " ). No entanto, não inclua aspas duplas no conteúdo do texto do texto_do_prompt_do_usuario. Aspas duplas dentro do texto do prompt fazem o comando falhar. Você pode usar aspas simples ( ' ) no texto do prompt.

PASSWORD num

opcional

A definição de senha a ser usada.

PASSWORD num não é usado para solicitar ou especificar uma senha real. A definição de senha faz referência a uma senha previamente fornecida ou definida com o comando PASSWORD, o comando SET PASSWORD ou a tag de análise PASSWORD.

num é o número da definição de senha. Por exemplo, se as duas senhas foram previamente fornecidas ou definidas em um script, ou no agendamento de um script de análise, PASSWORD 2 especifica o uso da senha nº 2.

Para obter mais informações sobre o fornecimento ou a definição de senhas, consulte:

Observação

AICOMMAND usa a chave de API de IA salva no registro local, caso uma chave tenha sido salva. Se nenhuma chave estiver salva, ou se você quiser usar uma chave diferente, deve usar PASSWORD. Para obter mais informações, consulte Configurações de conexão para um serviço de IA externo.

MODEL "informações_do_modelo"

Informações de identificação do modelo específico de IA que você deseja usar.

Por exemplo:

MODEL "anthropic.claude-3-5-sonnet-20241022-v2:0"

Um serviço de IA pode oferecer diferentes modelos que você pode usar.

Você pode usar qualquer modelo de linguagem grande (LLM) compatível com a OpenAI, ou seja, um modelo da OpenAI ou um modelo que utilize o mesmo esquema de API dos modelos da OpenAI.

URL "url_da_api_do_servico_de_ia"

A URL completa da API do serviço de IA.

Por exemplo:

URL "https://api.anthropic.com/v1"
BATCHSIZE numero_de_registros

opcional

O número de registros a incluir em cada lote enviado ao serviço de IA.

Se AICOMMAND falhar, tente especificar um tamanho de lote de 50 ou 25.

Se você não especificar BATCHSIZE, será usado o tamanho de lote padrão de 100 registros.

Um serviço de IA normalmente limita a quantidade de dados que processa em cada operação. Os registros de uma tabela do Analytics são enviados para um serviço de IA em lotes, para aumentar a probabilidade de permanecer dentro dos limites de dados. As respostas da IA para todos os lotes são reunidas em uma única tabela de saída do Analytics.
IF teste

opcional

Uma condição que precisa ser atendida para processar o registro atual. Os dados enviados ao serviço de IA incluem apenas os registros que atendem à condição.

Pelo menos um registro da tabela deve ser incluído pela condição IF. Se a condição excluir todos os registros da tabela, ocorre um erro e o comando não é executado.
WHILE teste

opcional

Uma expressão condicional que deve ser verdadeira para processar cada registro. O comando é executado até que a condição seja avaliada como falsa ou o fim da tabela seja alcançado.

Observação

Se você usar WHILE juntamente com FIRST ou NEXT, o processamento de registros será interrompido assim que um limite for alcançado.
FIRST intervalo | NEXT intervalo

opcional

O número de registros a ser processado:

  • PRIMEIROiniciar o processamento a partir do primeiro registro até alcançar o número de registros especificado
  • AVANÇARiniciar o processamento a partir do registro selecionado no momento até alcançar o número de registros especificado

Use intervalo para especificar o número de registros a serem processados.

Se você omitir FIRST e NEXT, todos os registros serão processados por padrão.

OPEN

opcional

Abre a tabela criada pelo comando após a execução do comando. Válido apenas se o comando criar uma tabela de saída.

Exemplos

Avaliação de fornecedores usando IA

Você deseja realizar uma verificação básica de uma tabela de fornecedores para identificar possíveis fornecedores fictícios. Você insere os campos de nome e endereço do fornecedor no serviço de IA e solicita que ele categorize os fornecedores como Common, Rare ou Unknown.

Quaisquer fornecedores categorizados como Desconhecido exigem investigação adicional para determinar se realmente existem.

OPEN Vendors
AICOMMAND FIELDS vendor_name address TO "ai_vendor_classification" USER_PROMPT "Este é um fornecedor amplamente conhecido? O valor de saída deve ser COMMON se for comum, RARE se for conhecido, mas incomum, e UNKNOWN caso contrário." MODEL "anthropic.claude-3-5-sonnet-20241022-v2:0" URL "https://hackfest-bedrock-proxy.diligentoneplatform-dev.com/api/v1"

Revisão de despesas usando IA

Você deseja revisar transações de cartão corporativo (P-card) e sinalizar quaisquer despesas em que exista discrepância entre o item ou serviço e o preço de compra. Você insere os campos de descrição da despesa e custo no serviço de IA e solicita que ele avalie se a despesa é razoável.

OPEN PcardTransactions
AICOMMAND FIELDS Description UnitCost TO "ai_expense_cost_review" USER_PROMPT "Dada a combinação de Description e Unit Cost, indique se o custo é típico ou incomum." MODEL "anthropic.claude-3-5-sonnet-20241022-v2:0" URL "https://hackfest-bedrock-proxy.diligentoneplatform-dev.com/api/v1"

Análise de sentimento de avaliações de hotéis usando IA

Você deseja realizar uma análise de sentimento e categorização do campo de comentários em texto livre em uma tabela contendo avaliações de clientes de hotel. Você solicita ao serviço de IA que categorize os comentários de acordo com as seis emoções humanas básicas.

OPEN hotel_reviews
AICOMMAND FIELDS reviews_rating reviews_text TO "ai_hotel_reviews_sentiment_analysis" USER_PROMPT "Realize uma análise de sentimento no campo reviews_text e categorize as avaliações de acordo com as seguintes emoções humanas básicas: Felicidade, Raiva, Medo, Tristeza, Nojo, Surpresa." MODEL "anthropic.claude-3-5-sonnet-20241022-v2:0" URL "https://hackfest-bedrock-proxy.diligentoneplatform-dev.com/api/v1" BATCHSIZE 50 OPEN

Observações

Como funciona a integração entre o Analytics e um serviço de IA externo

Selecionar campos, criar um prompt do usuário e executar AICOMMAND é o ponto inicial para a integração bidirecional entre o Analytics e um serviço de IA externo:

  1. AnalyticsAICOMMAND extrai o campo ou campos selecionados de uma tabela do Analytics e os salva em um arquivo CSV.

  2. AnalyticsAICOMMAND disponibiliza o prompt do usuário e as informações de conexão da API do serviço de IA para o script Python padrão ou para um script Python criado por você.

    Localização do script Python padrão:

    C:\Program Files (x86)\ACL Software\ACL for Windows <version>\acl_py_util\ai_main.py

    Cuidado

    Não mova o script Python padrão nem o altere de nenhuma forma. O funcionamento padrão do AICOMMAND depende de o script Python padrão estar no local correto e permanecer inalterado.

  3. PythonO script Python importa o arquivo CSV e o converte em um dataframe do Pandas.

  4. PythonO script Python envia o dataframe e o prompt do usuário para a API do serviço de IA. Para permanecer dentro dos limites de dados da API, o script envia o dataframe em lotes.

  5. Serviço de AIO serviço de IA processa o dataframe com base nas instruções do prompt do usuário.

  6. Serviço de AIO serviço de IA retorna o dataframe ao script Python com a adição da coluna ai_response, que contém os resultados do processamento da IA.

  7. PythonO script Python converte o dataframe retornado em uma tabela do Analytics e a exporta para o Analytics usando o nome da tabela de saída especificado em AICOMMAND.

  8. AnalyticsVocê pode abrir a tabela de saída no Analytics para visualizar os resultados do processamento da IA ou usar os resultados como base para análises adicionais de dados.

Usando seu próprio script Python

Você pode usar seu próprio script Python com AICOMMAND. Crie o script com a lógica que você deseja para interagir com a API do serviço de IA. No AICOMMAND, use o parâmetro SCRIPT para especificar o caminho e o nome do arquivo do script.

Uma abordagem possível é copiar o script Python padrão usado pelo AICOMMAND como ponto de partida para o seu próprio script. O script padrão fica na pasta de instalação do Analytics. Se você instalou o Analytics no local padrão, o script fica aqui:

C:\Program Files (x86)\ACL Software\ACL for Windows <version>\acl_py_util\ai_main.py

Cuidado

Não mova o script Python padrão nem o altere de nenhuma forma. O funcionamento padrão do AICOMMAND depende de o script Python padrão estar no local correto e permanecer inalterado.

O script Python usado pelo AICOMMAND deve conter as configurações de conexão para o serviço de IA externo, seja ele o script padrão ou o seu próprio script. No seu script, você tem duas opções:

  • Usar as configurações de conexão do AnalyticsUse os valores de host, modelo e chave de API de IA especificados nos parâmetros do AICOMMAND.

    Para usar os valores do AICOMMAND no seu script Python, defina três variáveis ou copie as definições de variáveis do script Python padrão.

    an_api_key = os.getenv("ACL_PY_API_KEY")
ai_base_url = os.getenv("ACL_PY_AI_BASE_URL")
ai_model = os.getenv("ACL_PY_AI_MODEL")

  • Use seu próprio métodoUse seu próprio método para fornecer os valores de host, modelo e chave de API de IA. Se você usar seu próprio método, não precisa especificar os valores de conexão nos parâmetros do AICOMMAND.

Criar um campo de identificador exclusivo:

Se você quiser unir a tabela retornada do serviço de IA com a tabela de origem original, mas não tiver um campo de identificador único, pode usar a função RECNO( ) para criar um antes de usar o AICOMMAND.

  1. Na tabela de origem, crie um campo calculado chamado record_number que use a seguinte expressão:

    RECNO( )

    Para cada registro na tabela, a função RECNO( ) adiciona o número único do registro no campo record_number.

    Para obter mais informações, consulte DEFINE FIELD . . . Comando COMPUTED

  2. Use o AICOMMAND para processar dados usando um serviço de IA externo.

  3. Use o campo record_number como campo-chave comum para unir a tabela retornada do serviço de IA com a tabela de origem.

    Para obter mais informações, consulte Comando JOIN.

Separar múltiplos componentes no campo ai_response

Na tabela de saída retornada pelo AICOMMAND, os valores no campo ai_response podem conter vários componentes ou elementos. Por exemplo, o valor único mostrado abaixo contém quatro componentes: sentiment, sentiment_score, key_reasons e themes. O componente themes contém três valores individuais.

sentiment: Positive, sentiment_score: 0.6, key_reasons: key_reasons: quartos limpos, equipe simpática, problemas no café da manhã, themes: limpeza, equipe, alimentação

Para permitir análises posteriores, você pode isolar os componentes e valores em campos calculados separados que você cria usando as expressões calculadas mostradas abaixo.

Para informações gerais sobre como criar campos calculados, consulte Definir campos calculados.

Nome de campo calculado Expressão calculada Valor de resultado
sentiment 
REGEXREPLACE(ai_response, "sentiment:\s(.?),.", "$1")
 Positivo(a)
sentiment_score 
VALUE(REGEXREPLACE(ai_response, ".sentiment_score:\s(.?),.*", "$1"), 1)
 0.6
key_reasons 
REGEXREPLACE(ai_response, ".key_reasons:\s(.?),\sthemes.*", "$1")
 quartos limpos, equipe simpática, problemas no café da manhã
themes 
REGEXREPLACE(ai_response, ".themes:\s(.?)", "$1")
 limpeza, equipe, comida
theme_1 
SPLIT(REGEXREPLACE(ai_response, ".themes:\s(.?)", "$1"), ",", 1)
 limpeza
theme_2 
SPLIT(REGEXREPLACE(ai_response, ".themes:\s(.?)", "$1"), ",", 2)
 equipe
theme_3 
SPLIT(REGEXREPLACE(ai_response, ".themes:\s(.?)", "$1"), ",", 3)
 comida