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 )

---

deleteByMetadata

---

deleteByMetadata(colecao: string, filtroMetadados: Values) : void

Descrição

Remove todos os documentos de uma coleção que correspondam ao filtro de metadados fornecido. O filtro é obrigatório e não pode ser nulo nem vazio, para evitar eliminações acidentais de toda a coleção. Para apagar a coleção inteira utilize deleteCollection.

Como Usar

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

store.deleteByMetadata('artigos', filtro)
_log.info('Documentos com fonte=web removidos.')

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção de onde os documentos serão removidos.
filtroMetadados	Values	Objeto com pares chave-valor que identificam os documentos a remover. Não pode ser nulo nem vazio.

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 )

---

getAll

---

getAll(colecao: string) : Values

Descrição

Retorna todos os documentos de uma coleção, sem qualquer filtragem.

Como Usar

const documentos = store.getAll('artigos')

for (const doc of documentos) {
    _log.info(doc.get('id') + ' | ' + doc.get('text'))
}

Atributos

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

Retorno

( Values )

Lista com todos os documentos da coleção. Cada item contém: id, text, embedding, metadata e timestamp.

---

getAll(colecao: string, filtroMetadados: Values) : Values

Descrição

Retorna todos os documentos de uma coleção que correspondam ao filtro de metadados fornecido. O filtro é aplicado como correspondência exata por subconjunto JSON (operador @> do PostgreSQL). Para valores em lista, é utilizado = ANY() em vez do operador de subconjunto.

Como Usar

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

const documentos = store.getAll('artigos', filtro)

for (const doc of documentos) {
    _log.info(doc.get('id') + ' | ' + doc.get('text'))
}

Atributos

NOME	TIPO	DESCRIÇÃO
colecao	string	Nome da coleção a consultar.
filtroMetadados	Values	Objeto com pares chave-valor para filtrar os documentos pelos seus metadados. Se nulo ou vazio, retorna todos os documentos.

Retorno

( Values )

Lista dos documentos correspondentes. Cada item contém: id, text, embedding, metadata e timestamp.

---

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.

---