> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/docs/pt/acoes/workflow-concepts/workflow-steps/memory-steps/memory-search.md).

# Pesquisar na Base de Conhecimento

Pesquise semanticamente numa Base de Conhecimento

## O que é uma etapa de pesquisa na Base de Conhecimento?

A etapa de pesquisa na Base de Conhecimento permite pesquisar semanticamente os seus dados para fornecer conteúdo personalizado ou recomendações aos utilizadores.

Para obter mais informações sobre como configurar uma Base de Conhecimento, consulte a nossa página de documentação [aqui](https://docs.airops.com/docs/pt/contexto/knowledge-bases.md).

## Como configurar uma etapa de pesquisa na Base de Conhecimento

### Selecione uma base de conhecimento

Selecione o nome da sua base de conhecimento na lista pendente.

{% hint style="info" %}
**Seleção dinâmica da Base de Conhecimento:** Pode usar variáveis Liquid para selecionar dinamicamente em que Base de Conhecimento pesquisar durante a execução. Isto é útil quando tem várias Bases de Conhecimento e pretende escolher entre elas com base nas entradas do fluxo de trabalho ou nos resultados de etapas anteriores. Por exemplo: `{{input.knowledge_base_name}}`
{% endhint %}

### Número máximo de resultados

Escolha o número de resultados da Base de Conhecimento a devolver.

{% hint style="info" %}
O seu conteúdo é dividido em blocos de 1000 tokens, pelo que cada resultado terá cerca de 1000 tokens.
{% endhint %}

Se o seu LLM não estiver a devolver exatamente os resultados que procura, recomendamos que aumente o número de resultados e lhe peça para os sintetizar.

### Filtrar a Base de Conhecimento (opcional)

As Bases de Conhecimento têm dois modos de filtragem. Use filtros para restringir a pesquisa com base em metadados, incluindo etiquetas de metadados personalizadas que adicionou aos ficheiros da sua Base de Conhecimento.

#### Editor visual

O **Editor visual** permite filtrar dados com base em qualquer campo de metadados, incluindo:

* **Metadados personalizados** que adicionou (por exemplo, país, produto, público, tipo de conteúdo)
* **Metadados padrão** herdados da origem
* **Colunas de CSV/folha de cálculo** ao pesquisar dados estruturados

Por exemplo, se tiver estudos de caso etiquetados com um campo de metadados personalizados `country` pode aplicar um filtro para pesquisar apenas estudos de caso de uma região específica:

<figure><img src="https://31915162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-0c255f839731a2b355030815b3919c6c8c41219f%2Fkb-search-step-01-filter.png?alt=media" alt="Search Knowledge Base step on SpaceOps Case Studies with Max Results 3 and a filter for country equal United Kingdom"><figcaption><p>Filtrar os resultados da pesquisa por um valor de metadados.</p></figcaption></figure>

{% hint style="success" %}
**Filtragem dinâmica com entradas**

Torne os seus filtros dinâmicos usando entradas do fluxo de trabalho. Por exemplo, crie uma entrada chamada `region` e defina o filtro como: país é igual a `{{input.region}}`. Agora, quando executar o fluxo de trabalho com valores de região diferentes, pesquisará apenas os ficheiros relevantes da Base de Conhecimento.
{% endhint %}

#### Editor de código

Para casos de utilização mais complexos, pode usar o **Editor de código** que utiliza os operadores de consulta e projeção do MongoDB. Eis alguns operadores comuns:

* **$eq** - Igual a (para números, cadeias de caracteres e valores booleanos)
* **$ne** - Diferente de (para números, cadeias de caracteres e valores booleanos)
* **$gt** - Maior do que (para números)
* **$gte** - Maior ou igual a (para números)
* **$lt** - Menor do que (para números)
* **$lte** - Menor ou igual a (para números)
* **$in** - Contido no array (para strings ou números)
* **$nin** - Não contido no array (para strings ou números)

Vamos ver um exemplo rápido de como pode filtrar por metadados no seu fluxo de trabalho usando o nosso modelo «Q\&A». Neste exemplo específico, já preenchemos a nossa base de conhecimento com as constituições de vários países, bem como com metadados centrados no campo «country» para filtrar.

{% @arcade/embed url="<https://app.arcade.software/share/wdZVVd8LeM0QNGiSf9v9>" flowId="wdZVVd8LeM0QNGiSf9v9" %}

Para que a filtragem seja eficaz, recomendamos que leia o documento [«Metadados das bases de conhecimento»](https://docs.airops.com/docs/pt/contexto/knowledge-bases/knowledge-base-metadata.md) para garantir que está a fornecer os campos de metadados ideais para a filtragem.

### Consulta

A expressão utilizada para pesquisar na sua base de conhecimento texto semanticamente semelhante.

Como boa prática, recomendamos que utilize uma variável Liquid na sua consulta. Como os seus fluxos de trabalho se destinam a adaptar-se aos dados de entrada que fornece, normalmente não é aconselhável codificar a consulta para uma variável ou pergunta específica.

Como a base de conhecimento devolve os resultados mais *semanticamente* semelhantes, por vezes, uma cadeia de texto longa tem mais probabilidades de devolver os resultados pretendidos do que uma expressão específica e precisa. Recomendamos que teste a sua consulta para garantir que corresponde às suas necessidades.

## Variáveis Liquid nas etapas da base de conhecimento

As variáveis Liquid funcionam em TODAS as etapas da base de conhecimento, incluindo:

* **Pesquisar na base de conhecimento:** Utilize Liquid para consultas, filtros e seleção da base de conhecimento
* **Escrever na base de conhecimento:** Utilize Liquid para conteúdo e valores de metadados
* **Obter ficheiro da base de conhecimento:** Utilize Liquid para identificadores de ficheiros
* **Ler da base de conhecimento:** Utilize Liquid para seleção de registos

Isto permite criar fluxos de trabalho totalmente dinâmicos, nos quais as operações da base de conhecimento se adaptam aos dados de entrada ou aos resultados de etapas anteriores.

## Resultado da etapa de pesquisa na base de conhecimento

A etapa de pesquisa na base de conhecimento devolve uma lista de embeddings da base de conhecimento.

* **ID:** Um ID exclusivo baseado no ID do fragmento dos metadados, no ID do registo e no ID do documento do armazenamento vetorial.
* **Pontuação:** Uma [medida de semelhança semântica](https://en.wikipedia.org/wiki/Cosine_similarity).
* **Conteúdo:** O texto (ou as colunas) do seu documento que pode ser pesquisado.
* **Nome do documento:** Nome do documento que forneceu.
* **URL do ficheiro do documento:** O URL do ficheiro do documento original que carregou (se existir).
* **Metadados:** Quaisquer colunas que tenha fornecido como metadados.

```
[
  {
    "id": "vsdi:87:rid:1:cid:0",
    "score": 0.78703,
    "content": "Blog Title: How to Become a Prompt Engineer\\nBlog Content: In this blog, we're going to show you how to take your prompting...",
    "document_name": "AirOps Knowledge Base",
    "document_file_url": "https://app.airops.com/your_document_file.pdf",
    "metadata": {
      "__chunk_id": 0,
      "__record_id": "1",
      "__vector_store_document_id": 87,
      "title": "How to Become a Prompt Engineer",
      "description": "Aprenda a elevar as suas instruções a um nível superior.",
    }
  },
  {
    ...
  }
 ]
```

### Formatar resultados para etapas de LLM

O resultado da etapa de pesquisa na base de conhecimento é um bloco JSON, como mostrado acima. No entanto, como irá passar frequentemente este resultado a um LLM, é muito mais eficaz formatar os resultados em linguagem natural.

#### Formatar com a etapa de código

Uma das melhores formas de o fazer é utilizar a nossa etapa de código em conjunto com a sintaxe Liquid. O nosso modelo «Q\&A» mostra um ótimo exemplo de como o pode fazer:

<figure><img src="https://31915162-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FX2n5yPRPynbnWuO4SH0M%2Fuploads%2Fgit-blob-2ed6f56b0c0a1b00ebb39b0f0f0ca4abb7e59299%2Fkb-search-step-02-format-with-code.png?alt=media" alt="Case Study Q&#x26;A Workflow with a Run Code step that formats the Search Knowledge Base results before the Answer the question step"><figcaption><p>Formate os resultados da pesquisa com uma etapa de código antes de os passar ao LLM.</p></figcaption></figure>

A nossa etapa de código utiliza JavaScript para formatar o bloco JSON num formato mais natural, que a etapa de LLM consegue interpretar:

```javascript
return step_1.output.map(item => `Document Name: ${item.document_name}\nContent: ${item.content}\nConfidence Score: ${item.score}`).join('\n\n');
```

#### Formatar com Liquid

Também pode utilizar Liquid para formatar os resultados da etapa de pesquisa na base de conhecimento e passar contexto e dados formatados à etapa de LLM.

Modificamos o resultado do exemplo anterior apresentado acima, percorrendo cada fragmento e devolvendo o `metadata.title` e `metadata.description`:

```liquid
// Replace step_x.output

{% for chunk in step_x.output %} 
    Title: {{chunk.metadata.title}}
    Description: {{chunk.metadata.description}}
{% endfor %}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.airops.com/docs/pt/acoes/workflow-concepts/workflow-steps/memory-steps/memory-search.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
