AI PostgreVectorStore

Armazenamento vetorial baseado em PostgreSQL com a extensão pgvector.

Permite guardar, pesquisar e gerir documentos com os seus embeddings vetoriais em coleções isoladas por fornecedor. Suporta pesquisa por similaridade coseno, filtragem por metadados e inserção em lote com transação atómica.

A extensão pgvector é verificada e instalada automaticamente se não estiver presente. As tabelas de suporte são criadas automaticamente na primeira inicialização.

const vector = _ai.vector('default')
const client = _ai.client()
const chunker = _ai.contextRetrievalChunker()

// Criar a coleção se ainda não existir
if (!vector.collectionExists('netuno')) {
    vector.createCollection('netuno', 768)
}

// Recolher todos os ficheiros Markdown recursivamente
const files = collectFiles(_app.folder(_app.pathStorage() + '/netuno_docs'))

for (const path of files) {
    const file = _app.file(path)
    if (file.exists()) {
        const content = file.input().readAllAndClose()
        const chunks = chunker.markdown(content, 1500 * 3, 400)
        for (const chunk of chunks) {
            const options = _val.init()
                .set('encoding_format', 'float')
                .set('dimensions', 768)
            const embeddingResponse = client.embeddings(
                'embeddinggemma:latest',
                chunk.get('text'),
                options
            )
            const embedding = embeddingResponse.get('data').get(0).get('embedding')
            vector.add('netuno', embedding, chunk.get('text'), null)
        }
    }
}

function collectFiles(folder) {
    const list = _val.list()
    folder.list().forEach(item => {
        if (item.isDirectory()) {
            collectFiles(item).forEach(f => list.add(f))
        } else {
            const path = item.fullPath()
            if (path.endsWith('.md') || path.endsWith('.mdx')) {
                list.add(path)
            }
        }
    })
    return list
}

add

add(colecao: string, id: string, embedding: Values, texto: string, metadados: Values) : void

Descrição

Insere ou atualiza um documento numa coleção com um ID explícito. Se a coleção ainda não existir, é criada automaticamente com as dimensões do embedding fornecido. Se já existir um documento com o mesmo ID, o conteúdo, embedding e metadados são atualizados.

Como Usar

const options = _val.init()
    .set('encoding_format', 'float')
    .set('dimensions', 768)

const embeddingResponse = client.embeddings('embeddinggemma:latest', 'Texto do documento.', options)
const embedding = embeddingResponse.get('data').get(0).get('embedding')

vector.add('netuno', 'doc-001', embedding, 'Texto do documento.', _val.map().set('fonte', 'web'))

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção onde o documento será inserido.
id	string	Identificador único do documento. Se nulo ou vazio, é gerado automaticamente um UUID.
embedding	Values	Lista de valores numéricos que representam o vetor do documento.
texto	string	Conteúdo textual do documento a guardar.
metadados	Values	Objeto com metadados arbitrários associados ao documento, utilizável para filtragem em pesquisas. Pode ser nulo.

Retorno

( void )

add(colecao: string, embedding: Values, texto: string, metadados: Values) : void

Descrição

Insere ou atualiza um documento numa coleção com um ID gerado automaticamente. Se a coleção ainda não existir, é criada automaticamente com as dimensões do embedding fornecido. Se já existir um documento com o mesmo ID, o conteúdo, embedding e metadados são atualizados.

Como Usar

const options = _val.init()
    .set('encoding_format', 'float')
    .set('dimensions', 768)

const embeddingResponse = client.embeddings('embeddinggemma:latest', 'Texto do documento.', options)
const embedding = embeddingResponse.get('data').get(0).get('embedding')

vector.add('netuno', embedding, 'Texto do documento.', _val.map().set('fonte', 'web'))

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção onde o documento será inserido.
embedding	Values	Lista de valores numéricos que representam o vetor do documento.
texto	string	Conteúdo textual do documento a guardar.
metadados	Values	Objeto com metadados arbitrários associados ao documento, utilizável para filtragem em pesquisas. Pode ser nulo.

Retorno

( void )

addBatch

addBatch(colecao: string, documentos: Values) : void

Descrição

Insere ou atualiza múltiplos documentos numa coleção numa única transação atómica. Se algum documento falhar, toda a operação é revertida. Cada item da lista deve ser um objeto com os campos text (obrigatório), embedding (obrigatório), id (opcional, gerado automaticamente se ausente) e metadata (opcional).

Como Usar

const options = _val.init().set('encoding_format', 'float').set('dimensions', 768)

const documentos = _val.list()

const textos = _val.list().add('Primeiro documento.').add('Segundo documento.')
const embeddingResponse = client.embeddings('embeddinggemma:latest', textos, options)

const data = embeddingResponse.get('data')
for (let i = 0; i < data.size(); i++) {
    const item = data.get(i)
    documentos.add(
        _val.map()
            .set('text', textos.get(i))
            .set('embedding', item.get('embedding'))
            .set('metadata', _val.map().set('index', i))
    )
}

vector.addBatch('netuno', documentos)

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção onde os documentos serão inseridos.
documentos	Values	Lista de documentos. Cada item deve conter: `text` (texto do documento), `embedding` (vetor numérico), `id` (opcional) e `metadata` (opcional).

Retorno

( void )

collectionExists

collectionExists(colecao: string) : boolean

Descrição

Verifica se uma coleção existe para o fornecedor configurado.

Como Usar

if (!store.collectionExists('artigos')) {
    store.createCollection('artigos', 1536)
}

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção a verificar.

Retorno

( boolean )

Verdadeiro se a coleção existe, falso caso contrário.

count

count(colecao: string) : int

Descrição

Retorna o número total de documentos numa coleção para o fornecedor configurado.

Como Usar

const total = store.count('artigos')
_log.info('Total de documentos: ' + total)

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção a contar.

Retorno

( int )

Número total de documentos na coleção. Retorna 0 se a coleção não existir ou estiver vazia.

createCollection

createCollection(colecao: string, dimensoes: int) : boolean

Descrição

Cria explicitamente uma coleção com um número fixo de dimensões. Se a coleção já existir, a operação é ignorada silenciosamente e retorna false. Normalmente não é necessário chamar este método diretamente, pois a coleção é criada automaticamente na primeira chamada a add ou addBatch.

Como Usar

const criada = store.createCollection('artigos', 1536)
if (criada) {
    _log.info('Coleção criada com sucesso.')
}

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção a criar.
dimensoes	int	Número de dimensões dos vetores desta coleção. Deve ser maior que zero e consistente com o modelo de embeddings utilizado.

Retorno

( boolean )

Verdadeiro se a coleção foi criada, falso se já existia.

delete

delete(colecao: string, id: string) : void

Descrição

Remove um documento específico de uma coleção pelo seu ID. Se o ID não existir, a operação é ignorada silenciosamente.

Como Usar

store.delete('artigos', 'doc-001')

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção que contém o documento.
id	string	Identificador único do documento a remover.

Retorno

( void )

deleteCollection

deleteCollection(colecao: string) : void

Descrição

Remove uma coleção inteira e todos os seus documentos. A operação é em cascata: apagar a coleção apaga automaticamente todos os documentos associados.

Como Usar

store.deleteCollection('artigos')

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção a remover.

Retorno

( void )

getProvider

getProvider() : string

Retorno

( string )

init

init() : void

Retorno

( void )

isInitialized

isInitialized() : boolean

Retorno

( boolean )

listCollections

listCollections() : Values

Descrição

Lista todas as coleções existentes para o fornecedor configurado, incluindo o número de dimensões e o total de documentos em cada uma.

Como Usar

const colecoes = store.listCollections()

for (const c of colecoes) {
    _log.info(c.get('name') + ' | dims: ' + c.get('dimensions') + ' | docs: ' + c.get('count'))
}

Retorno

( Values )

Lista de coleções, cada uma com os campos: name (nome da coleção), dimensions (número de dimensões) e count (total de documentos).

provider

provider(provider: string) : org.netuno.tritao.ai.vector.VectorStore

Atributos

NOME	TIPO	DESCRIÇÃO
provider	string

Retorno

( org.netuno.tritao.ai.vector.VectorStore )

search

search(colecao: string, embedding: Values, topK: int) : Values

Descrição

Pesquisa os documentos mais similares ao embedding fornecido numa coleção, utilizando distância coseno. Retorna os topK documentos mais próximos, ordenados por pontuação de similaridade decrescente.

Como Usar

const resultados = store.search('artigos', embedding, 5)

for (const r of resultados) {
    _log.info('Score: ' + r.get('score') + ' | ' + r.get('text'))
}

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção onde a pesquisa será realizada.
embedding	Values	Vetor de consulta para comparação com os documentos armazenados.
topK	int	Número máximo de resultados a retornar.

Retorno

( Values )

Lista de documentos correspondentes, cada um com os campos: id, text, embedding, metadata, score (0.0–1.0) e timestamp.

search(colecao: string, embedding: Values, topK: int, filtro: Values) : Values

Descrição

Pesquisa os documentos mais similares ao embedding fornecido numa coleção, com filtragem adicional por metadados. O filtro é aplicado como correspondência exata por subconjunto JSON (operador @> do PostgreSQL). Retorna os topK documentos mais próximos que satisfaçam o filtro, ordenados por pontuação de similaridade decrescente.

Como Usar

const filtro = _val.map().set('fonte', 'pdf')

const resultados = store.search('artigos', embedding, 5, filtro)

for (const r of resultados) {
    _log.info('Score: ' + r.get('score') + ' | ' + r.get('text'))
}

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção onde a pesquisa será realizada.
embedding	Values	Vetor de consulta para comparação com os documentos armazenados.
topK	int	Número máximo de resultados a retornar.
filtro	Values	Objeto de metadados para filtrar os resultados. Apenas documentos cujos metadados contenham todos os pares chave-valor do filtro são retornados.

Retorno

( Values )

Lista de documentos correspondentes, cada um com os campos: id, text, embedding, metadata, score (0.0–1.0) e timestamp.

add​

add(colecao: string, id: string, embedding: Values, texto: string, metadados: Values) : void​

Descrição​

Como Usar​

Atributos​

Retorno​

add(colecao: string, embedding: Values, texto: string, metadados: Values) : void​

Descrição​

Como Usar​

Atributos​

Retorno​

addBatch​

addBatch(colecao: string, documentos: Values) : void​

Descrição​

Como Usar​

Atributos​

Retorno​

collectionExists​

collectionExists(colecao: string) : boolean​

Descrição​

Como Usar​

Atributos​

Retorno​

count​

count(colecao: string) : int​

Descrição​

Como Usar​

Atributos​

Retorno​

createCollection​

createCollection(colecao: string, dimensoes: int) : boolean​

Descrição​

Como Usar​

Atributos​

Retorno​

delete​

delete(colecao: string, id: string) : void​

Descrição​

Como Usar​

Atributos​

Retorno​

deleteCollection​

deleteCollection(colecao: string) : void​

Descrição​

Como Usar​

Atributos​

Retorno​

getProvider​

getProvider() : string​

Retorno​

init​

init() : void​

Retorno​

isInitialized​

isInitialized() : boolean​

Retorno​

listCollections​

listCollections() : Values​

Descrição​

Como Usar​

Retorno​

provider​

provider(provider: string) : org.netuno.tritao.ai.vector.VectorStore​

Atributos​

Retorno​

search​

search(colecao: string, embedding: Values, topK: int) : Values​

Descrição​

Como Usar​

Atributos​

Retorno​

search(colecao: string, embedding: Values, topK: int, filtro: Values) : Values​

Descrição​

Como Usar​

Atributos​

Retorno​

add

add(colecao: string, id: string, embedding: Values, texto: string, metadados: Values) : void

Descrição

Como Usar

Atributos

Retorno

add(colecao: string, embedding: Values, texto: string, metadados: Values) : void

Descrição

Como Usar

Atributos

Retorno

addBatch

addBatch(colecao: string, documentos: Values) : void

Descrição

Como Usar

Atributos

Retorno

collectionExists

collectionExists(colecao: string) : boolean

Descrição

Como Usar

Atributos

Retorno

count

count(colecao: string) : int

Descrição

Como Usar

Atributos

Retorno

createCollection

createCollection(colecao: string, dimensoes: int) : boolean

Descrição

Como Usar

Atributos

Retorno

delete

delete(colecao: string, id: string) : void

Descrição

Como Usar

Atributos

Retorno

deleteCollection

deleteCollection(colecao: string) : void

Descrição

Como Usar

Atributos

Retorno

getProvider

getProvider() : string

Retorno

init

init() : void

Retorno

isInitialized

isInitialized() : boolean

Retorno

listCollections

listCollections() : Values

Descrição

Como Usar

Retorno

provider

provider(provider: string) : org.netuno.tritao.ai.vector.VectorStore

Atributos

Retorno

search

search(colecao: string, embedding: Values, topK: int) : Values

Descrição

Como Usar

Atributos

Retorno

search(colecao: string, embedding: Values, topK: int, filtro: Values) : Values

Descrição

Como Usar

Atributos

Retorno