Funções de machine learning

Documentação sobre funções de machine learning

​

evalMLMethod

A previsão com modelos de regressão ajustados usa a função evalMLMethod. Veja o link em linearRegression.

​

stochasticLinearRegression

A função de agregação stochasticLinearRegression implementa o método de descida estocástica do gradiente usando um modelo linear e a função de perda MSE. Usa evalMLMethod para fazer previsões em novos dados.

​

stochasticLogisticRegression

A função de agregação stochasticLogisticRegression implementa o método de descida de gradiente estocástico para o problema de classificação binária. Usa evalMLMethod para fazer previsões com novos dados.

​

naiveBayesClassifier

Classifica o texto de entrada usando um modelo Naive Bayes com n-gramas e Laplace smoothing. O modelo deve ser configurado no ClickHouse antes de ser usado.

Sintaxe

naiveBayesClassifier(model_name, input_text);

Argumentos

• model_name — Nome do modelo pré-configurado. String O modelo deve estar definido nos arquivos de configuração do ClickHouse (veja abaixo).
• input_text — Texto a ser classificado. String A entrada é processada exatamente como foi fornecida (com maiúsculas/minúsculas e pontuação preservadas).

Valor retornado

• ID da classe prevista como um inteiro sem sinal. UInt32 Os IDs de classe correspondem às categorias definidas durante a criação do modelo.

Exemplo

Classifique um texto com um modelo de detecção de idioma:

SELECT naiveBayesClassifier('language', 'How are you?');

┌─naiveBayesClassifier('language', 'How are you?')─┐
│ 0                                                │
└──────────────────────────────────────────────────┘

O resultado 0 pode representar inglês, enquanto 1 pode indicar francês — o significado das classes depende dos seus dados de treinamento.

---

​

Detalhes de implementação

Algoritmo Utiliza o algoritmo de classificação Naive Bayes com suavização de Laplace para lidar com n-gramas não observados, com base nas probabilidades de n-gramas descritas neste documento.

Principais recursos

• Suporta n-gramas de qualquer tamanho
• Três modos de tokenização:
  • byte: Opera sobre bytes brutos. Cada byte é um token.
  • codepoint: Opera sobre valores escalares Unicode decodificados de UTF‑8. Cada ponto de código é um token.
  • token: Separa por sequências de espaços em branco Unicode (regex \s+). Os tokens são substrings sem espaços em branco; a pontuação faz parte do token se estiver adjacente (por exemplo, “you?” é um único token).

---

​

Configuração do modelo

Você pode encontrar aqui um exemplo de código-fonte para criar um modelo Naive Bayes para detecção de idioma.

Além disso, aqui estão disponíveis modelos de exemplo e seus respectivos arquivos de configuração.

Veja abaixo um exemplo de configuração para um modelo Naive Bayes no ClickHouse:

<clickhouse>
    <nb_models>
        <model>
            <name>sentiment</name>
            <path>/etc/clickhouse-server/config.d/sentiment.bin</path>
            <n>2</n>
            <mode>token</mode>
            <alpha>1.0</alpha>
            <priors>
                <prior>
                    <class>0</class>
                    <value>0.6</value>
                </prior>
                <prior>
                    <class>1</class>
                    <value>0.4</value>
                </prior>
            </priors>
        </model>
    </nb_models>
</clickhouse>

Parâmetros de Configuração

Parâmetro	Descrição	Exemplo	Padrão
name	Identificador exclusivo do modelo	language_detection	Obrigatório
path	Caminho completo para o binário do modelo	/etc/clickhouse-server/config.d/language_detection.bin	Obrigatório
mode	Método de tokenização: - byte: Sequências de bytes - codepoint: Caracteres Unicode - token: Tokens de palavras	token	Obrigatório
n	Tamanho do n-grama (modo token): - 1=palavra única - 2=pares de palavras - 3=trios de palavras	2	Obrigatório
alpha	Fator de suavização de Laplace usado durante a classificação para lidar com n-gramas que não aparecem no modelo	0.5	1.0
priors	Probabilidades das classes (% de documentos pertencentes a uma classe)	60% classe 0, 40% classe 1	Distribuição igual

Guia de Treinamento do Modelo

Formato do Arquivo Em formato legível por humanos, para n=1 e o modo token, o modelo pode se parecer com isto:

<class_id> <n-gram> <count>
0 excellent 15
1 refund 28

Para n=3 e o modo codepoint, pode ser assim:

<class_id> <n-gram> <count>
0 exc 15
1 ref 28

O formato legível para humanos não é usado diretamente pelo ClickHouse; ele deve ser convertido para o formato binário descrito abaixo.

Detalhes do formato binário Cada n-gram é armazenado da seguinte forma:

1. class_id de 4 bytes (UInt, little-endian)
2. comprimento, em bytes, do n-gram de 4 bytes (UInt, little-endian)
3. bytes brutos do n-gram
4. count de 4 bytes (UInt, little-endian)

Requisitos de pré-processamento Antes de o modelo ser criado a partir do corpus de documentos, os documentos precisam ser pré-processados para extrair n-grams de acordo com os valores especificados de mode e n. As etapas a seguir descrevem esse pré-processamento:

1. Adicione marcadores de delimitação no início e no fim de cada documento com base no modo de tokenização:

   • Byte: 0x01 (início), 0xFF (fim)
   • Codepoint: U+10FFFE (início), U+10FFFF (fim)
   • Token: <s> (início), </s> (fim)

   Observação: (n - 1) tokens são adicionados tanto no início quanto no fim do documento.

2. Exemplo para n=3 no modo token:

   • Documento: "ClickHouse is fast"
   • Processado como: <s> <s> ClickHouse is fast </s> </s>
   • Trigramas gerados:
     • <s> <s> ClickHouse
     • <s> ClickHouse is
     • ClickHouse is fast
     • is fast </s>
     • fast </s> </s>

Para simplificar a criação de modelos para os modos byte e codepoint, pode ser conveniente primeiro tokenizar o documento em tokens (uma lista de bytes para o modo byte e uma lista de codepoints para o modo codepoint). Em seguida, acrescente n - 1 tokens de início no início e n - 1 tokens de fim no final do documento. Por fim, gere os n-gramas e grave-os no arquivo serializado.

---

​

assignCentroid

Introduzido em: v26.8.0

Retorna o id do centróide mais próximo (L2) de um vetor. Os centróides são fornecidos como uma matriz constante de matrizes de números de ponto flutuante, em que o id é a posição, começando em 0, nessa matriz, ou como o nome de um Dicionário que contém os atributos cid e vec, em que o id é cid.

Esta função não é determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

assignCentroid(vec, centroids | dict_name)

Argumentos

• vec — Vetor a ser atribuído. Sua dimensão deve corresponder à dimensão dos centroides. Tipos diferentes de Float32 são convertidos para Float32, que é o tipo usado pelo kernel de pontuação. Array(Float32) ou Array(Float64) ou Array(BFloat16)
• centroids — Os centroides em relação aos quais a pontuação é calculada, que devem ser constantes. Podem ser fornecidos como um array de arrays de números de ponto flutuante não vazios e de mesmo tamanho; nesse caso, o id é a posição baseada em 0 nesse array. Também podem ser fornecidos como o nome de um Dicionário com um atributo cid de tipo inteiro sem sinal compatível com UInt32 e um atributo vec do tipo Array(Float32); nesse caso, o id é cid. O dicionário é lido uma vez e armazenado em cache até ser recarregado. Array(Array(Float32)) ou Array(Array(Float64)) ou Array(Array(BFloat16)) ou String

Valor retornado

O id do centroide mais próximo. UInt32

Exemplos

Centroides inline

Query

SELECT assignCentroid([1.0, 2.0]::Array(Float32), [[0.0, 0.0], [1.0, 2.0]]::Array(Array(Float32)))

Response

1

​

evalMLMethod

Introduzido em: v20.1.0

Aplica um modelo de machine learning treinado às features de entrada para gerar previsões.

Sintaxe

evalMLMethod(model, x1[, x2, ...])

Argumentos

• model — O modelo de machine learning treinado. AggregateFunctionState
• x1, x2, ... — Valores das características para a predição. Float* ou (U)Int*

Valor retornado

Retorna o valor previsto com base no modelo treinado. Float64

Exemplos

Exemplo de uso

Query

CREATE TABLE trips (pickup_datetime DateTime('UTC'), trip_distance Float64, total_amount Float64) ENGINE = Memory;

-- A fare of 3, plus 2.5 for every unit of distance.
INSERT INTO trips
SELECT toDateTime('2020-01-01 00:00:00', 'UTC') + number * 60, number % 10 + 1, 2.5 * (number % 10 + 1) + 3
FROM numbers(1000);

-- One model per year of the data.
CREATE TABLE models ENGINE = Memory AS
SELECT
    toYear(pickup_datetime) AS year,
    stochasticLinearRegressionState(0.01, 0.0, 10, 'SGD')(total_amount, trip_distance) AS model
FROM trips
GROUP BY year;

SELECT
    trip_distance,
    round(evalMLMethod(model, trip_distance), 2) AS predicted,
    total_amount
FROM trips
LEFT JOIN models ON year = toYear(pickup_datetime)
ORDER BY pickup_datetime
LIMIT 5

Response

┌─trip_distance─┬─predicted─┬─total_amount─┐
│             1 │      4.05 │          5.5 │
│             2 │      6.79 │            8 │
│             3 │      9.53 │         10.5 │
│             4 │     12.28 │           13 │
│             5 │     15.02 │         15.5 │
└───────────────┴───────────┴──────────────┘

​

naiveBayesClassifier

Introduzido em: v25.11.0

Classifica o texto de entrada usando um NAIVE_BAYES Dicionário. Retorna o mesmo valor de classe previsto por dictGet(dictionary_name, class_attribute, input_text), em que class_attribute é o nome do atributo do rótulo de classe configurado no layout do dicionário. Diferentemente de dictGet, o tipo do resultado é sempre UInt32, em vez do tipo declarado do atributo de classe, e input_text deve ser uma String (nenhuma conversão do tipo de chave é aplicada).

Esta função é não determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

naiveBayesClassifier(dictionary_name, input_text)

Argumentos

• dictionary_name — Nome de um dicionário com o layout NAIVE_BAYES. String
• input_text — Texto a ser classificado. String

Valor retornado

ID da classe prevista. UInt32

Exemplos

Classificação de texto

Query

-- A dictionary built from the token counts of two classes: 0 for a positive review, 1 for a negative one.
CREATE TABLE review_tokens (ngram String, class_id UInt32, count UInt64) ENGINE = Memory;
INSERT INTO review_tokens VALUES ('good', 0, 5), ('great', 0, 4), ('excellent', 0, 3), ('bad', 1, 5), ('awful', 1, 4), ('terrible', 1, 3);

CREATE DICTIONARY sentiment (ngram String, class_id UInt32 DEFAULT 0, count UInt64 DEFAULT 0)
PRIMARY KEY ngram
SOURCE(CLICKHOUSE(TABLE 'review_tokens'))
LAYOUT(NAIVE_BAYES(class_attribute 'class_id' n 1 mode 'token'))
LIFETIME(0);

SELECT naiveBayesClassifier('sentiment', 'a good and great film') AS class_id;

Response

┌─class_id─┐
│        0 │
└──────────┘

​

naiveBayesClassifierWithAllProbs

Introduzido em: v26.7.0

Classifica o texto de entrada usando um dicionário NAIVE_BAYES e retorna todas as classes com suas probabilidades, em ordem da mais provável para a menos provável.

Esta função é não determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

naiveBayesClassifierWithAllProbs(dictionary_name, input_text)

Argumentos

• dictionary_name — Nome de um dicionário com o layout NAIVE_BAYES. String
• input_text — Texto a ser classificado. String

Valor retornado

Array de tuplas (class_id, probability) ordenadas da mais provável para a menos provável. Array(Tuple(UInt32, Float64))

Exemplos

Todas as probabilidades de classe

Query

-- A dictionary built from the token counts of two classes: 0 for a positive review, 1 for a negative one.
CREATE TABLE review_tokens (ngram String, class_id UInt32, count UInt64) ENGINE = Memory;
INSERT INTO review_tokens VALUES ('good', 0, 5), ('great', 0, 4), ('excellent', 0, 3), ('bad', 1, 5), ('awful', 1, 4), ('terrible', 1, 3);

CREATE DICTIONARY sentiment (ngram String, class_id UInt32 DEFAULT 0, count UInt64 DEFAULT 0)
PRIMARY KEY ngram
SOURCE(CLICKHOUSE(TABLE 'review_tokens'))
LAYOUT(NAIVE_BAYES(class_attribute 'class_id' n 1 mode 'token'))
LIFETIME(0);

SELECT arrayMap(p -> (p.1, round(p.2, 4)), naiveBayesClassifierWithAllProbs('sentiment', 'a good and great film')) AS predictions;

Response

┌─predictions─────────────┐
│ [(0,0.9677),(1,0.0323)] │
└─────────────────────────┘

​

naiveBayesClassifierWithProb

Introduzido em: v26.7.0

Classifica o texto de entrada usando um dicionário NAIVE_BAYES e retorna a classe predita com sua probabilidade.

Esta função é não determinística: pode retornar resultados diferentes para os mesmos argumentos.

Sintaxe

naiveBayesClassifierWithProb(dictionary_name, input_text)

Argumentos

• dictionary_name — Nome de um dicionário com o layout NAIVE_BAYES. String
• input_text — Texto a ser classificado. String

Valor retornado

Tuple com (class_id, probabilidade). Tuple(UInt32, Float64)

Exemplos

Classificação com probabilidade

Query

-- A dictionary built from the token counts of two classes: 0 for a positive review, 1 for a negative one.
CREATE TABLE review_tokens (ngram String, class_id UInt32, count UInt64) ENGINE = Memory;
INSERT INTO review_tokens VALUES ('good', 0, 5), ('great', 0, 4), ('excellent', 0, 3), ('bad', 1, 5), ('awful', 1, 4), ('terrible', 1, 3);

CREATE DICTIONARY sentiment (ngram String, class_id UInt32 DEFAULT 0, count UInt64 DEFAULT 0)
PRIMARY KEY ngram
SOURCE(CLICKHOUSE(TABLE 'review_tokens'))
LAYOUT(NAIVE_BAYES(class_attribute 'class_id' n 1 mode 'token'))
LIFETIME(0);

WITH naiveBayesClassifierWithProb('sentiment', 'a good and great film') AS p
SELECT (p.1, round(p.2, 4)) AS prediction;

Response

┌─prediction─┐
│ (0,0.9677) │
└────────────┘