mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-04-30 23:02:50 +00:00
Add pt-BR docs translation (#3039)
* docs: add pt-br translations Powered by a CrewAI Flow https://github.com/danielfsbarreto/docs_translator * Update mcp/overview.mdx brazilian docs Its en-US counterpart was updated after I did a pass, so now it includes the new section about @CrewBase
This commit is contained in:
Daniel Barreto
69
docs/pt-BR/tools/database-data/mysqltool.mdx
Normal file
69
docs/pt-BR/tools/database-data/mysqltool.mdx
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
title: Busca RAG no MySQL
|
||||
description: O `MySQLSearchTool` foi projetado para buscar em bancos de dados MySQL e retornar os resultados mais relevantes.
|
||||
icon: database
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Esta ferramenta foi desenvolvida para facilitar buscas semânticas em tabelas de bancos de dados MySQL. Utilizando a tecnologia RAG (Retrieve and Generate),
|
||||
o MySQLSearchTool oferece aos usuários um meio eficiente de consultar o conteúdo de tabelas do banco de dados, especificamente adaptado para bancos MySQL.
|
||||
Ela simplifica o processo de encontrar dados relevantes por meio de consultas de busca semântica, tornando-se um recurso valioso para quem precisa
|
||||
realizar consultas avançadas em grandes conjuntos de dados dentro de um banco de dados MySQL.
|
||||
|
||||
## Instalação
|
||||
|
||||
Para instalar o pacote `crewai_tools` e utilizar o MySQLSearchTool, execute o seguinte comando no seu terminal:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## Exemplo
|
||||
|
||||
Abaixo está um exemplo demonstrando como usar o MySQLSearchTool para realizar uma busca semântica em uma tabela de um banco de dados MySQL:
|
||||
|
||||
```python Code
|
||||
from crewai_tools import MySQLSearchTool
|
||||
|
||||
# Inicialize a ferramenta com o URI do banco de dados e o nome da tabela de destino
|
||||
tool = MySQLSearchTool(
|
||||
db_uri='mysql://user:password@localhost:3306/mydatabase',
|
||||
table_name='employees'
|
||||
)
|
||||
```
|
||||
|
||||
## Argumentos
|
||||
|
||||
O MySQLSearchTool requer os seguintes argumentos para sua operação:
|
||||
|
||||
- `db_uri`: Uma string representando o URI do banco de dados MySQL a ser consultado. Este argumento é obrigatório e deve incluir os detalhes de autenticação necessários e o local do banco de dados.
|
||||
- `table_name`: Uma string especificando o nome da tabela dentro do banco de dados na qual será realizada a busca semântica. Este argumento é obrigatório.
|
||||
|
||||
## Modelo e embeddings personalizados
|
||||
|
||||
Por padrão, a ferramenta utiliza o OpenAI tanto para embeddings quanto para sumarização. Para customizar o modelo, você pode usar um dicionário de configuração conforme o exemplo:
|
||||
|
||||
```python Code
|
||||
tool = MySQLSearchTool(
|
||||
config=dict(
|
||||
llm=dict(
|
||||
provider="ollama", # ou google, openai, anthropic, llama2, ...
|
||||
config=dict(
|
||||
model="llama2",
|
||||
# temperature=0.5,
|
||||
# top_p=1,
|
||||
# stream=true,
|
||||
),
|
||||
),
|
||||
embedder=dict(
|
||||
provider="google",
|
||||
config=dict(
|
||||
model="models/embedding-001",
|
||||
task_type="retrieval_document",
|
||||
# title="Embeddings",
|
||||
),
|
||||
),
|
||||
)
|
||||
)
|
||||
```
|
||||
76
docs/pt-BR/tools/database-data/nl2sqltool.mdx
Normal file
76
docs/pt-BR/tools/database-data/nl2sqltool.mdx
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
title: NL2SQL Tool
|
||||
description: O `NL2SQLTool` foi projetado para converter linguagem natural em consultas SQL.
|
||||
icon: language
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
Esta ferramenta é utilizada para converter linguagem natural em consultas SQL. Quando passada para o agente, ela irá gerar as consultas e, em seguida, utilizá-las para interagir com o banco de dados.
|
||||
|
||||
Isso possibilita múltiplos fluxos de trabalho, como por exemplo ter um Agente acessando o banco de dados para buscar informações com base em um objetivo e, então, usar essas informações para gerar uma resposta, relatório ou qualquer outro tipo de saída. Além disso, permite que o Agente atualize o banco de dados de acordo com seu objetivo.
|
||||
|
||||
**Atenção**: Certifique-se de que o Agente tenha acesso a um Read-Replica ou que seja permitido que o Agente execute consultas de inserção/atualização no banco de dados.
|
||||
|
||||
## Requisitos
|
||||
|
||||
- SqlAlchemy
|
||||
- Qualquer biblioteca compatível com o banco de dados (ex.: psycopg2, mysql-connector-python)
|
||||
|
||||
## Instalação
|
||||
|
||||
Instale o pacote crewai_tools
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
## Uso
|
||||
|
||||
Para utilizar o NL2SQLTool, você precisa passar a URI do banco de dados para a ferramenta. O formato da URI deve ser `dialect+driver://username:password@host:port/database`.
|
||||
|
||||
```python Code
|
||||
from crewai_tools import NL2SQLTool
|
||||
|
||||
# psycopg2 foi instalado para rodar este exemplo com PostgreSQL
|
||||
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")
|
||||
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config["researcher"],
|
||||
allow_delegation=False,
|
||||
tools=[nl2sql]
|
||||
)
|
||||
```
|
||||
|
||||
## Exemplo
|
||||
|
||||
O objetivo principal da tarefa era:
|
||||
|
||||
"Recupere a receita mensal média, máxima e mínima para cada cidade, mas inclua apenas cidades que tenham mais de um usuário. Além disso, conte o número de usuários em cada cidade e classifique os resultados pela receita mensal média em ordem decrescente"
|
||||
|
||||
Assim, o Agente tentou obter informações do banco de dados; a primeira vez está errada, então o Agente tenta novamente, consegue a informação correta e repassa para o próximo agente.
|
||||
|
||||
|
||||
|
||||
|
||||
O segundo objetivo da tarefa foi:
|
||||
|
||||
"Revise os dados e crie um relatório detalhado e, em seguida, crie a tabela no banco de dados com os campos baseados nos dados fornecidos. Inclua informações sobre a receita mensal média, máxima e mínima para cada cidade, mas apenas inclua cidades que possuam mais de um usuário. Também conte o número de usuários em cada cidade e classifique os resultados pela receita mensal média em ordem decrescente."
|
||||
|
||||
Agora as coisas começam a ficar interessantes: o Agente gera a consulta SQL não só para criar a tabela, mas também inserir os dados na tabela. E, ao final, o Agente ainda retorna o relatório final que condiz exatamente com o que estava no banco de dados.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Este é um exemplo simples de como o NL2SQLTool pode ser utilizado para interagir com o banco de dados e gerar relatórios baseados nos dados do banco.
|
||||
|
||||
A ferramenta oferece possibilidades infinitas para a lógica do Agente e como ele pode interagir com o banco de dados.
|
||||
|
||||
```md
|
||||
DB -> Agent -> ... -> Agent -> DB
|
||||
```
|
||||
58
docs/pt-BR/tools/database-data/overview.mdx
Normal file
58
docs/pt-BR/tools/database-data/overview.mdx
Normal file
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: "Visão Geral"
|
||||
description: "Conecte-se a bancos de dados, armazenamentos vetoriais e data warehouses para acesso abrangente aos dados"
|
||||
icon: "face-smile"
|
||||
---
|
||||
|
||||
Essas ferramentas permitem que seus agentes interajam com diversos sistemas de banco de dados, desde bancos de dados SQL tradicionais até armazenamentos vetoriais modernos e data warehouses.
|
||||
|
||||
## **Ferramentas Disponíveis**
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="MySQL Tool" icon="database" href="/pt-BR/tools/database-data/mysqltool">
|
||||
Conecte-se e faça consultas a bancos de dados MySQL com operações SQL.
|
||||
</Card>
|
||||
|
||||
<Card title="PostgreSQL Search" icon="elephant" href="/pt-BR/tools/database-data/pgsearchtool">
|
||||
Pesquise e consulte bancos de dados PostgreSQL de forma eficiente.
|
||||
</Card>
|
||||
|
||||
<Card title="Snowflake Search" icon="snowflake" href="/pt-BR/tools/database-data/snowflakesearchtool">
|
||||
Acesse o data warehouse Snowflake para análises e relatórios.
|
||||
</Card>
|
||||
|
||||
<Card title="NL2SQL Tool" icon="language" href="/pt-BR/tools/database-data/nl2sqltool">
|
||||
Converta automaticamente consultas em linguagem natural para comandos SQL.
|
||||
</Card>
|
||||
|
||||
<Card title="Qdrant Vector Search" icon="vector-square" href="/pt-BR/tools/database-data/qdrantvectorsearchtool">
|
||||
Pesquise embeddings vetoriais usando o banco de dados vetorial Qdrant.
|
||||
</Card>
|
||||
|
||||
<Card title="Weaviate Vector Search" icon="network-wired" href="/pt-BR/tools/database-data/weaviatevectorsearchtool">
|
||||
Realize buscas semânticas com o banco de dados vetorial Weaviate.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## **Casos de Uso Comuns**
|
||||
|
||||
- **Análise de Dados**: Consulte bancos de dados para inteligência de negócios e relatórios
|
||||
- **Busca Vetorial**: Encontre conteúdos similares utilizando embeddings semânticos
|
||||
- **Operações ETL**: Extraia, transforme e carregue dados entre sistemas
|
||||
- **Análise em Tempo Real**: Acesse dados ao vivo para tomada de decisões
|
||||
|
||||
```python
|
||||
from crewai_tools import MySQLTool, QdrantVectorSearchTool, NL2SQLTool
|
||||
|
||||
# Create database tools
|
||||
mysql_db = MySQLTool()
|
||||
vector_search = QdrantVectorSearchTool()
|
||||
nl_to_sql = NL2SQLTool()
|
||||
|
||||
# Add to your agent
|
||||
agent = Agent(
|
||||
role="Data Analyst",
|
||||
tools=[mysql_db, vector_search, nl_to_sql],
|
||||
goal="Extract insights from various data sources"
|
||||
)
|
||||
```
|
||||
82
docs/pt-BR/tools/database-data/pgsearchtool.mdx
Normal file
82
docs/pt-BR/tools/database-data/pgsearchtool.mdx
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: PG RAG Search
|
||||
description: O `PGSearchTool` foi desenvolvido para pesquisar bancos de dados PostgreSQL e retornar os resultados mais relevantes.
|
||||
icon: elephant
|
||||
---
|
||||
|
||||
## Visão geral
|
||||
|
||||
<Note>
|
||||
O PGSearchTool está atualmente em desenvolvimento. Este documento descreve a funcionalidade e a interface pretendidas.
|
||||
Conforme o desenvolvimento avança, esteja ciente de que alguns recursos podem não estar disponíveis ou podem mudar.
|
||||
</Note>
|
||||
|
||||
## Descrição
|
||||
|
||||
O PGSearchTool é concebido como uma ferramenta poderosa para facilitar buscas semânticas em tabelas de bancos de dados PostgreSQL. Aproveitando tecnologia avançada de Recuperação e Geração (RAG),
|
||||
ele visa fornecer um meio eficiente para consultar o conteúdo de tabelas de banco de dados, especificamente voltado para bancos de dados PostgreSQL.
|
||||
O objetivo da ferramenta é simplificar o processo de encontrar dados relevantes por meio de consultas semânticas, oferecendo um recurso valioso para usuários que precisam realizar buscas avançadas em
|
||||
grandes volumes de dados dentro de um ambiente PostgreSQL.
|
||||
|
||||
## Instalação
|
||||
|
||||
O pacote `crewai_tools`, que incluirá o PGSearchTool assim que for lançado, pode ser instalado usando o comando abaixo:
|
||||
|
||||
```shell
|
||||
pip install 'crewai[tools]'
|
||||
```
|
||||
|
||||
<Note>
|
||||
O PGSearchTool ainda não está disponível na versão atual do pacote `crewai_tools`. Este comando de instalação será atualizado assim que a ferramenta for lançada.
|
||||
</Note>
|
||||
|
||||
## Exemplo de Uso
|
||||
|
||||
Abaixo está um exemplo proposto mostrando como utilizar o PGSearchTool para realizar uma busca semântica em uma tabela dentro de um banco de dados PostgreSQL:
|
||||
|
||||
```python Code
|
||||
from crewai_tools import PGSearchTool
|
||||
|
||||
# Inicialize a ferramenta com a URI do banco de dados e o nome da tabela alvo
|
||||
tool = PGSearchTool(
|
||||
db_uri='postgresql://user:password@localhost:5432/mydatabase',
|
||||
table_name='employees'
|
||||
)
|
||||
```
|
||||
|
||||
## Argumentos
|
||||
|
||||
O PGSearchTool foi projetado para exigir os seguintes argumentos para seu funcionamento:
|
||||
|
||||
| Argumento | Tipo | Descrição |
|
||||
|:---------------|:---------|:---------------------------------------------------------------------------------------------------------------------------------|
|
||||
| **db_uri** | `string` | **Obrigatório**. Uma string que representa a URI do banco de dados PostgreSQL a ser consultado. Este argumento será obrigatório e deve incluir os detalhes necessários de autenticação e a localização do banco de dados. |
|
||||
| **table_name** | `string` | **Obrigatório**. Uma string que especifica o nome da tabela dentro do banco de dados na qual a busca semântica será realizada. Este argumento também será obrigatório. |
|
||||
|
||||
## Modelo Personalizado e Embeddings
|
||||
|
||||
A ferramenta pretende usar OpenAI tanto para embeddings quanto para sumarização por padrão. Os usuários terão a opção de personalizar o modelo usando um dicionário de configuração, conforme mostrado abaixo:
|
||||
|
||||
```python Code
|
||||
tool = PGSearchTool(
|
||||
config=dict(
|
||||
llm=dict(
|
||||
provider="ollama", # ou google, openai, anthropic, llama2, ...
|
||||
config=dict(
|
||||
model="llama2",
|
||||
# temperature=0.5,
|
||||
# top_p=1,
|
||||
# stream=true,
|
||||
),
|
||||
),
|
||||
embedder=dict(
|
||||
provider="google", # ou openai, ollama, ...
|
||||
config=dict(
|
||||
model="models/embedding-001",
|
||||
task_type="retrieval_document",
|
||||
# title="Embeddings",
|
||||
),
|
||||
),
|
||||
)
|
||||
)
|
||||
```
|
||||
272
docs/pt-BR/tools/database-data/qdrantvectorsearchtool.mdx
Normal file
272
docs/pt-BR/tools/database-data/qdrantvectorsearchtool.mdx
Normal file
@@ -0,0 +1,272 @@
|
||||
---
|
||||
title: 'Qdrant Vector Search Tool'
|
||||
description: 'Capacidades de busca semântica para agentes CrewAI usando o banco de dados vetorial Qdrant'
|
||||
icon: vector-square
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
A ferramenta Qdrant Vector Search permite adicionar capacidades de busca semântica aos seus agentes CrewAI utilizando o [Qdrant](https://qdrant.tech/), um mecanismo de busca por similaridade vetorial. Com essa ferramenta, seus agentes podem pesquisar em documentos armazenados em uma coleção Qdrant usando similaridade semântica.
|
||||
|
||||
## Instalação
|
||||
|
||||
Instale os pacotes necessários:
|
||||
|
||||
```bash
|
||||
uv add qdrant-client
|
||||
```
|
||||
|
||||
## Uso Básico
|
||||
|
||||
Veja um exemplo mínimo de como utilizar a ferramenta:
|
||||
|
||||
```python
|
||||
from crewai import Agent
|
||||
from crewai_tools import QdrantVectorSearchTool
|
||||
|
||||
# Inicialize a ferramenta
|
||||
qdrant_tool = QdrantVectorSearchTool(
|
||||
qdrant_url="your_qdrant_url",
|
||||
qdrant_api_key="your_qdrant_api_key",
|
||||
collection_name="your_collection"
|
||||
)
|
||||
|
||||
# Crie um agente que utiliza a ferramenta
|
||||
agent = Agent(
|
||||
role="Research Assistant",
|
||||
goal="Find relevant information in documents",
|
||||
tools=[qdrant_tool]
|
||||
)
|
||||
|
||||
# A ferramenta usará automaticamente embeddings da OpenAI
|
||||
# e retornará os 3 resultados mais relevantes com pontuação > 0.35
|
||||
```
|
||||
|
||||
## Exemplo Completo e Funcional
|
||||
|
||||
Veja um exemplo completo mostrando como:
|
||||
1. Extrair texto de um PDF
|
||||
2. Gerar embeddings usando OpenAI
|
||||
3. Armazenar no Qdrant
|
||||
4. Criar um fluxo de trabalho RAG agente CrewAI para busca semântica
|
||||
|
||||
```python
|
||||
import os
|
||||
import uuid
|
||||
import pdfplumber
|
||||
from openai import OpenAI
|
||||
from dotenv import load_dotenv
|
||||
from crewai import Agent, Task, Crew, Process, LLM
|
||||
from crewai_tools import QdrantVectorSearchTool
|
||||
from qdrant_client import QdrantClient
|
||||
from qdrant_client.models import PointStruct, Distance, VectorParams
|
||||
|
||||
# Carregar variáveis de ambiente
|
||||
load_dotenv()
|
||||
|
||||
# Inicializar cliente OpenAI
|
||||
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
|
||||
|
||||
# Extrair texto do PDF
|
||||
def extract_text_from_pdf(pdf_path):
|
||||
text = []
|
||||
with pdfplumber.open(pdf_path) as pdf:
|
||||
for page in pdf.pages:
|
||||
page_text = page.extract_text()
|
||||
if page_text:
|
||||
text.append(page_text.strip())
|
||||
return text
|
||||
|
||||
# Gerar embeddings da OpenAI
|
||||
def get_openai_embedding(text):
|
||||
response = client.embeddings.create(
|
||||
input=text,
|
||||
model="text-embedding-3-small"
|
||||
)
|
||||
return response.data[0].embedding
|
||||
|
||||
# Armazenar texto e embeddings no Qdrant
|
||||
def load_pdf_to_qdrant(pdf_path, qdrant, collection_name):
|
||||
# Extrair texto do PDF
|
||||
text_chunks = extract_text_from_pdf(pdf_path)
|
||||
|
||||
# Criar coleção no Qdrant
|
||||
if qdrant.collection_exists(collection_name):
|
||||
qdrant.delete_collection(collection_name)
|
||||
qdrant.create_collection(
|
||||
collection_name=collection_name,
|
||||
vectors_config=VectorParams(size=1536, distance=Distance.COSINE)
|
||||
)
|
||||
|
||||
# Armazenar embeddings
|
||||
points = []
|
||||
for chunk in text_chunks:
|
||||
embedding = get_openai_embedding(chunk)
|
||||
points.append(PointStruct(
|
||||
id=str(uuid.uuid4()),
|
||||
vector=embedding,
|
||||
payload={"text": chunk}
|
||||
))
|
||||
qdrant.upsert(collection_name=collection_name, points=points)
|
||||
|
||||
# Inicializar cliente Qdrant e carregar dados
|
||||
qdrant = QdrantClient(
|
||||
url=os.getenv("QDRANT_URL"),
|
||||
api_key=os.getenv("QDRANT_API_KEY")
|
||||
)
|
||||
collection_name = "example_collection"
|
||||
pdf_path = "path/to/your/document.pdf"
|
||||
load_pdf_to_qdrant(pdf_path, qdrant, collection_name)
|
||||
|
||||
# Inicializar ferramenta de busca Qdrant
|
||||
qdrant_tool = QdrantVectorSearchTool(
|
||||
qdrant_url=os.getenv("QDRANT_URL"),
|
||||
qdrant_api_key=os.getenv("QDRANT_API_KEY"),
|
||||
collection_name=collection_name,
|
||||
limit=3,
|
||||
score_threshold=0.35
|
||||
)
|
||||
|
||||
# Criar agentes CrewAI
|
||||
search_agent = Agent(
|
||||
role="Senior Semantic Search Agent",
|
||||
goal="Find and analyze documents based on semantic search",
|
||||
backstory="""You are an expert research assistant who can find relevant
|
||||
information using semantic search in a Qdrant database.""",
|
||||
tools=[qdrant_tool],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
answer_agent = Agent(
|
||||
role="Senior Answer Assistant",
|
||||
goal="Generate answers to questions based on the context provided",
|
||||
backstory="""You are an expert answer assistant who can generate
|
||||
answers to questions based on the context provided.""",
|
||||
tools=[qdrant_tool],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# Definir tarefas
|
||||
search_task = Task(
|
||||
description="""Search for relevant documents about the {query}.
|
||||
Your final answer should include:
|
||||
- The relevant information found
|
||||
- The similarity scores of the results
|
||||
- The metadata of the relevant documents""",
|
||||
agent=search_agent
|
||||
)
|
||||
|
||||
answer_task = Task(
|
||||
description="""Given the context and metadata of relevant documents,
|
||||
generate a final answer based on the context.""",
|
||||
agent=answer_agent
|
||||
)
|
||||
|
||||
# Executar fluxo CrewAI
|
||||
crew = Crew(
|
||||
agents=[search_agent, answer_agent],
|
||||
tasks=[search_task, answer_task],
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
|
||||
result = crew.kickoff(
|
||||
inputs={"query": "What is the role of X in the document?"}
|
||||
)
|
||||
print(result)
|
||||
```
|
||||
|
||||
## Parâmetros da Ferramenta
|
||||
|
||||
### Parâmetros Obrigatórios
|
||||
- `qdrant_url` (str): URL do seu servidor Qdrant
|
||||
- `qdrant_api_key` (str): Chave de API para autenticação com o Qdrant
|
||||
- `collection_name` (str): Nome da coleção Qdrant a ser pesquisada
|
||||
|
||||
### Parâmetros Opcionais
|
||||
- `limit` (int): Número máximo de resultados a serem retornados (padrão: 3)
|
||||
- `score_threshold` (float): Limite mínimo de similaridade (padrão: 0.35)
|
||||
- `custom_embedding_fn` (Callable[[str], list[float]]): Função personalizada para vetorização de textos
|
||||
|
||||
## Parâmetros de Busca
|
||||
|
||||
A ferramenta aceita estes parâmetros em seu schema:
|
||||
- `query` (str): Consulta de busca para encontrar documentos similares
|
||||
- `filter_by` (str, opcional): Campo de metadado para filtrar
|
||||
- `filter_value` (str, opcional): Valor para filtrar
|
||||
|
||||
## Formato de Retorno
|
||||
|
||||
A ferramenta retorna resultados no formato JSON:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"metadata": {
|
||||
// Todos os metadados armazenados junto com o documento
|
||||
},
|
||||
"context": "O conteúdo textual real do documento",
|
||||
"distance": 0.95 // Pontuação de similaridade
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Embedding Padrão
|
||||
|
||||
Por padrão, a ferramenta utiliza o modelo `text-embedding-3-small` da OpenAI para vetorização. Isso requer:
|
||||
- Chave de API da OpenAI definida na variável de ambiente: `OPENAI_API_KEY`
|
||||
|
||||
## Embeddings Personalizados
|
||||
|
||||
Em vez de utilizar o modelo padrão de embeddings, você pode utilizar sua própria função de embeddings nos casos em que:
|
||||
|
||||
1. Deseja usar um modelo de embeddings diferente (ex: Cohere, HuggingFace, modelos Ollama)
|
||||
2. Precisa reduzir custos utilizando modelos de código aberto
|
||||
3. Tem requisitos específicos quanto à dimensão dos vetores ou à qualidade dos embeddings
|
||||
4. Deseja utilizar embeddings específicos para determinado domínio (ex: textos médicos ou jurídicos)
|
||||
|
||||
Veja um exemplo utilizando um modelo HuggingFace:
|
||||
|
||||
```python
|
||||
from transformers import AutoTokenizer, AutoModel
|
||||
import torch
|
||||
|
||||
# Carregar modelo e tokenizer
|
||||
tokenizer = AutoTokenizer.from_pretrained('sentence-transformers/all-MiniLM-L6-v2')
|
||||
model = AutoModel.from_pretrained('sentence-transformers/all-MiniLM-L6-v2')
|
||||
|
||||
def custom_embeddings(text: str) -> list[float]:
|
||||
# Tokenizar e obter saídas do modelo
|
||||
inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True)
|
||||
outputs = model(**inputs)
|
||||
|
||||
# Usar mean pooling para obter o embedding do texto
|
||||
embeddings = outputs.last_hidden_state.mean(dim=1)
|
||||
|
||||
# Converter para lista de floats e retornar
|
||||
return embeddings[0].tolist()
|
||||
|
||||
# Usar embeddings personalizados com a ferramenta
|
||||
tool = QdrantVectorSearchTool(
|
||||
qdrant_url="your_url",
|
||||
qdrant_api_key="your_key",
|
||||
collection_name="your_collection",
|
||||
custom_embedding_fn=custom_embeddings # Passe sua função personalizada
|
||||
)
|
||||
```
|
||||
|
||||
## Tratamento de Erros
|
||||
|
||||
A ferramenta trata os seguintes erros específicos:
|
||||
- Lança ImportError se `qdrant-client` não estiver instalado (com opção de instalar automaticamente)
|
||||
- Lança ValueError se `QDRANT_URL` não estiver definido
|
||||
- Solicita instalação de `qdrant-client` se estiver ausente utilizando `uv add qdrant-client`
|
||||
|
||||
## Variáveis de Ambiente
|
||||
|
||||
Variáveis de ambiente obrigatórias:
|
||||
```bash
|
||||
export QDRANT_URL="your_qdrant_url" # Se não for informado no construtor
|
||||
export QDRANT_API_KEY="your_api_key" # Se não for informado no construtor
|
||||
export OPENAI_API_KEY="your_openai_key" # Se estiver usando embeddings padrão
|
||||
```
|
||||
202
docs/pt-BR/tools/database-data/snowflakesearchtool.mdx
Normal file
202
docs/pt-BR/tools/database-data/snowflakesearchtool.mdx
Normal file
@@ -0,0 +1,202 @@
|
||||
---
|
||||
title: Snowflake Search Tool
|
||||
description: O `SnowflakeSearchTool` permite que agentes CrewAI executem consultas SQL e realizem buscas semânticas em data warehouses Snowflake.
|
||||
icon: snowflake
|
||||
---
|
||||
|
||||
# `SnowflakeSearchTool`
|
||||
|
||||
## Descrição
|
||||
|
||||
O `SnowflakeSearchTool` foi desenvolvido para conectar-se a data warehouses Snowflake e executar consultas SQL com recursos avançados como pool de conexões, lógica de tentativas e execução assíncrona. Esta ferramenta permite que agentes CrewAI interajam com bases de dados Snowflake, sendo ideal para tarefas de análise de dados, relatórios e inteligência de negócios que requerem acesso a dados empresariais armazenados no Snowflake.
|
||||
|
||||
## Instalação
|
||||
|
||||
Para utilizar esta ferramenta, é necessário instalar as dependências requeridas:
|
||||
|
||||
```shell
|
||||
uv add cryptography snowflake-connector-python snowflake-sqlalchemy
|
||||
```
|
||||
|
||||
Ou, alternativamente:
|
||||
|
||||
```shell
|
||||
uv sync --extra snowflake
|
||||
```
|
||||
|
||||
## Passos para Começar
|
||||
|
||||
Para usar eficazmente o `SnowflakeSearchTool`, siga estes passos:
|
||||
|
||||
1. **Instale as Dependências**: Instale os pacotes necessários usando um dos comandos acima.
|
||||
2. **Configure a Conexão com o Snowflake**: Crie um objeto `SnowflakeConfig` com suas credenciais do Snowflake.
|
||||
3. **Inicialize a Ferramenta**: Crie uma instância da ferramenta com a configuração necessária.
|
||||
4. **Execute Consultas**: Utilize a ferramenta para rodar consultas SQL no seu banco de dados Snowflake.
|
||||
|
||||
## Exemplo
|
||||
|
||||
O exemplo a seguir demonstra como usar o `SnowflakeSearchTool` para consultar dados de um banco de dados Snowflake:
|
||||
|
||||
```python Code
|
||||
from crewai import Agent, Task, Crew
|
||||
from crewai_tools import SnowflakeSearchTool, SnowflakeConfig
|
||||
|
||||
# Create Snowflake configuration
|
||||
config = SnowflakeConfig(
|
||||
account="your_account",
|
||||
user="your_username",
|
||||
password="your_password",
|
||||
warehouse="COMPUTE_WH",
|
||||
database="your_database",
|
||||
snowflake_schema="your_schema"
|
||||
)
|
||||
|
||||
# Initialize the tool
|
||||
snowflake_tool = SnowflakeSearchTool(config=config)
|
||||
|
||||
# Define an agent that uses the tool
|
||||
data_analyst_agent = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze data from Snowflake database",
|
||||
backstory="An expert data analyst who can extract insights from enterprise data.",
|
||||
tools=[snowflake_tool],
|
||||
verbose=True,
|
||||
)
|
||||
|
||||
# Example task to query sales data
|
||||
query_task = Task(
|
||||
description="Query the sales data for the last quarter and summarize the top 5 products by revenue.",
|
||||
expected_output="A summary of the top 5 products by revenue for the last quarter.",
|
||||
agent=data_analyst_agent,
|
||||
)
|
||||
|
||||
# Create and run the crew
|
||||
crew = Crew(agents=[data_analyst_agent],
|
||||
tasks=[query_task])
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
Você também pode customizar a ferramenta com parâmetros adicionais:
|
||||
|
||||
```python Code
|
||||
# Initialize the tool with custom parameters
|
||||
snowflake_tool = SnowflakeSearchTool(
|
||||
config=config,
|
||||
pool_size=10,
|
||||
max_retries=5,
|
||||
retry_delay=2.0,
|
||||
enable_caching=True
|
||||
)
|
||||
```
|
||||
|
||||
## Parâmetros
|
||||
|
||||
### Parâmetros do SnowflakeConfig
|
||||
|
||||
A classe `SnowflakeConfig` aceita os seguintes parâmetros:
|
||||
|
||||
- **account**: Obrigatório. Identificador da conta Snowflake.
|
||||
- **user**: Obrigatório. Nome de usuário do Snowflake.
|
||||
- **password**: Opcional*. Senha do Snowflake.
|
||||
- **private_key_path**: Opcional*. Caminho para o arquivo de chave privada (alternativa à senha).
|
||||
- **warehouse**: Obrigatório. Nome do warehouse do Snowflake.
|
||||
- **database**: Obrigatório. Banco de dados padrão.
|
||||
- **snowflake_schema**: Obrigatório. Schema padrão.
|
||||
- **role**: Opcional. Papel de usuário Snowflake.
|
||||
- **session_parameters**: Opcional. Parâmetros de sessão personalizados como dicionário.
|
||||
|
||||
*É necessário fornecer `password` ou `private_key_path`.
|
||||
|
||||
### Parâmetros do SnowflakeSearchTool
|
||||
|
||||
O `SnowflakeSearchTool` aceita os seguintes parâmetros durante a inicialização:
|
||||
|
||||
- **config**: Obrigatório. Um objeto `SnowflakeConfig` contendo detalhes da conexão.
|
||||
- **pool_size**: Opcional. Número de conexões no pool. O padrão é 5.
|
||||
- **max_retries**: Opcional. Número máximo de tentativas para consultas que falharem. Padrão é 3.
|
||||
- **retry_delay**: Opcional. Intervalo entre tentativas em segundos. Padrão é 1.0.
|
||||
- **enable_caching**: Opcional. Define se o cache de resultados de consultas será habilitado. Padrão é True.
|
||||
|
||||
## Uso
|
||||
|
||||
Ao utilizar o `SnowflakeSearchTool`, você deve fornecer os seguintes parâmetros:
|
||||
|
||||
- **query**: Obrigatório. Consulta SQL a ser executada.
|
||||
- **database**: Opcional. Sobrescreve o banco de dados padrão especificado na configuração.
|
||||
- **snowflake_schema**: Opcional. Sobrescreve o schema padrão especificado na configuração.
|
||||
- **timeout**: Opcional. Tempo limite da consulta em segundos. O padrão é 300.
|
||||
|
||||
A ferramenta retornará os resultados da consulta como uma lista de dicionários, onde cada dicionário representa uma linha com os nomes das colunas como chaves.
|
||||
|
||||
```python Code
|
||||
# Example of using the tool with an agent
|
||||
data_analyst = Agent(
|
||||
role="Data Analyst",
|
||||
goal="Analyze sales data from Snowflake",
|
||||
backstory="An expert data analyst with experience in SQL and data visualization.",
|
||||
tools=[snowflake_tool],
|
||||
verbose=True
|
||||
)
|
||||
|
||||
# The agent will use the tool with parameters like:
|
||||
# query="SELECT product_name, SUM(revenue) as total_revenue FROM sales GROUP BY product_name ORDER BY total_revenue DESC LIMIT 5"
|
||||
# timeout=600
|
||||
|
||||
# Create a task for the agent
|
||||
analysis_task = Task(
|
||||
description="Query the sales database and identify the top 5 products by revenue for the last quarter.",
|
||||
expected_output="A detailed analysis of the top 5 products by revenue.",
|
||||
agent=data_analyst
|
||||
)
|
||||
|
||||
# Run the task
|
||||
crew = Crew(
|
||||
agents=[data_analyst],
|
||||
tasks=[analysis_task]
|
||||
)
|
||||
result = crew.kickoff()
|
||||
```
|
||||
|
||||
## Recursos Avançados
|
||||
|
||||
### Pool de Conexões
|
||||
|
||||
O `SnowflakeSearchTool` implementa pool de conexões para melhorar a performance reutilizando conexões com o banco de dados. Você pode controlar o tamanho do pool com o parâmetro `pool_size`.
|
||||
|
||||
### Tentativas Automáticas
|
||||
|
||||
A ferramenta tenta novamente consultas que falharem automaticamente, usando backoff exponencial. O comportamento das tentativas pode ser ajustado pelos parâmetros `max_retries` e `retry_delay`.
|
||||
|
||||
### Cache de Resultados de Consultas
|
||||
|
||||
Para melhorar a performance em consultas repetidas, a ferramenta pode armazenar resultados em cache. Este recurso está habilitado por padrão, mas pode ser desativado ao definir `enable_caching=False`.
|
||||
|
||||
### Autenticação por Par de Chaves
|
||||
|
||||
Além de autenticação por senha, a ferramenta também suporta autenticação por par de chaves para maior segurança:
|
||||
|
||||
```python Code
|
||||
config = SnowflakeConfig(
|
||||
account="your_account",
|
||||
user="your_username",
|
||||
private_key_path="/path/to/your/private/key.p8",
|
||||
warehouse="COMPUTE_WH",
|
||||
database="your_database",
|
||||
snowflake_schema="your_schema"
|
||||
)
|
||||
```
|
||||
|
||||
## Tratamento de Erros
|
||||
|
||||
O `SnowflakeSearchTool` inclui uma gestão abrangente de erros para situações comuns no Snowflake:
|
||||
|
||||
- Falhas de conexão
|
||||
- Timeout de consultas
|
||||
- Erros de autenticação
|
||||
- Erros de banco de dados e schema
|
||||
|
||||
Quando um erro ocorrer, a ferramenta tentará repetir a operação (se estiver configurado) e fornecerá informações detalhadas sobre o erro.
|
||||
|
||||
## Conclusão
|
||||
|
||||
O `SnowflakeSearchTool` oferece uma maneira poderosa de integrar data warehouses Snowflake com agentes CrewAI. Com recursos como pool de conexões, tentativas automáticas e cache de consultas, ele possibilita acesso eficiente e confiável aos dados empresariais. Esta ferramenta é particularmente útil para tarefas de análise de dados, relatórios e inteligência de negócios que demandam acesso a dados estruturados armazenados no Snowflake.
|
||||
162
docs/pt-BR/tools/database-data/weaviatevectorsearchtool.mdx
Normal file
162
docs/pt-BR/tools/database-data/weaviatevectorsearchtool.mdx
Normal file
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: Busca Vetorial Weaviate
|
||||
description: O `WeaviateVectorSearchTool` foi projetado para buscar documentos semanticamente similares em um banco de dados vetorial Weaviate.
|
||||
icon: network-wired
|
||||
---
|
||||
|
||||
## Visão Geral
|
||||
|
||||
O `WeaviateVectorSearchTool` foi especificamente desenvolvido para realizar buscas semânticas em documentos armazenados em um banco de dados vetorial Weaviate. Essa ferramenta permite encontrar documentos semanticamente similares a uma determinada consulta, aproveitando o poder das embeddings vetoriais para resultados de busca mais precisos e contextualmente relevantes.
|
||||
|
||||
[Weaviate](https://weaviate.io/) é um banco de dados vetorial que armazena e consulta embeddings vetoriais, possibilitando recursos de busca semântica.
|
||||
|
||||
## Instalação
|
||||
|
||||
Para incorporar esta ferramenta ao seu projeto, é necessário instalar o cliente Weaviate:
|
||||
|
||||
```shell
|
||||
uv add weaviate-client
|
||||
```
|
||||
|
||||
## Etapas para Começar
|
||||
|
||||
Para utilizar efetivamente o `WeaviateVectorSearchTool`, siga as etapas abaixo:
|
||||
|
||||
1. **Instalação dos Pacotes**: Confirme que os pacotes `crewai[tools]` e `weaviate-client` estão instalados em seu ambiente Python.
|
||||
2. **Configuração do Weaviate**: Configure um cluster Weaviate. Você pode seguir as instruções na [documentação do Weaviate](https://weaviate.io/developers/wcs/manage-clusters/connect).
|
||||
3. **Chaves de API**: Obtenha a URL do seu cluster Weaviate e a chave de API correspondente.
|
||||
4. **Chave de API da OpenAI**: Certifique-se de que você tenha uma chave de API da OpenAI definida nas variáveis de ambiente como `OPENAI_API_KEY`.
|
||||
|
||||
## Exemplo
|
||||
|
||||
O exemplo a seguir demonstra como inicializar a ferramenta e executar uma busca:
|
||||
|
||||
```python Code
|
||||
from crewai_tools import WeaviateVectorSearchTool
|
||||
|
||||
# Inicializar a ferramenta
|
||||
tool = WeaviateVectorSearchTool(
|
||||
collection_name='example_collections',
|
||||
limit=3,
|
||||
weaviate_cluster_url="https://your-weaviate-cluster-url.com",
|
||||
weaviate_api_key="your-weaviate-api-key",
|
||||
)
|
||||
|
||||
@agent
|
||||
def search_agent(self) -> Agent:
|
||||
'''
|
||||
Este agente utiliza o WeaviateVectorSearchTool para buscar
|
||||
documentos semanticamente similares em um banco de dados vetorial Weaviate.
|
||||
'''
|
||||
return Agent(
|
||||
config=self.agents_config["search_agent"],
|
||||
tools=[tool]
|
||||
)
|
||||
```
|
||||
|
||||
## Parâmetros
|
||||
|
||||
O `WeaviateVectorSearchTool` aceita os seguintes parâmetros:
|
||||
|
||||
- **collection_name**: Obrigatório. O nome da coleção a ser pesquisada.
|
||||
- **weaviate_cluster_url**: Obrigatório. A URL do cluster Weaviate.
|
||||
- **weaviate_api_key**: Obrigatório. A chave de API para o cluster Weaviate.
|
||||
- **limit**: Opcional. O número de resultados a serem retornados. O padrão é `3`.
|
||||
- **vectorizer**: Opcional. O vetorizador a ser utilizado. Se não for informado, será utilizado o `text2vec_openai` com o modelo `nomic-embed-text`.
|
||||
- **generative_model**: Opcional. O modelo generativo a ser utilizado. Se não for informado, será utilizado o `gpt-4o` da OpenAI.
|
||||
|
||||
## Configuração Avançada
|
||||
|
||||
Você pode personalizar o vetorizador e o modelo generativo utilizados pela ferramenta:
|
||||
|
||||
```python Code
|
||||
from crewai_tools import WeaviateVectorSearchTool
|
||||
from weaviate.classes.config import Configure
|
||||
|
||||
# Configurar modelo personalizado para vetorizador e modelo generativo
|
||||
tool = WeaviateVectorSearchTool(
|
||||
collection_name='example_collections',
|
||||
limit=3,
|
||||
vectorizer=Configure.Vectorizer.text2vec_openai(model="nomic-embed-text"),
|
||||
generative_model=Configure.Generative.openai(model="gpt-4o-mini"),
|
||||
weaviate_cluster_url="https://your-weaviate-cluster-url.com",
|
||||
weaviate_api_key="your-weaviate-api-key",
|
||||
)
|
||||
```
|
||||
|
||||
## Pré-carregando Documentos
|
||||
|
||||
Você pode pré-carregar seu banco de dados Weaviate com documentos antes de utilizar a ferramenta:
|
||||
|
||||
```python Code
|
||||
import os
|
||||
from crewai_tools import WeaviateVectorSearchTool
|
||||
import weaviate
|
||||
from weaviate.classes.init import Auth
|
||||
|
||||
# Conectar ao Weaviate
|
||||
client = weaviate.connect_to_weaviate_cloud(
|
||||
cluster_url="https://your-weaviate-cluster-url.com",
|
||||
auth_credentials=Auth.api_key("your-weaviate-api-key"),
|
||||
headers={"X-OpenAI-Api-Key": "your-openai-api-key"}
|
||||
)
|
||||
|
||||
# Obter ou criar coleção
|
||||
test_docs = client.collections.get("example_collections")
|
||||
if not test_docs:
|
||||
test_docs = client.collections.create(
|
||||
name="example_collections",
|
||||
vectorizer_config=Configure.Vectorizer.text2vec_openai(model="nomic-embed-text"),
|
||||
generative_config=Configure.Generative.openai(model="gpt-4o"),
|
||||
)
|
||||
|
||||
# Carregar documentos
|
||||
docs_to_load = os.listdir("knowledge")
|
||||
with test_docs.batch.dynamic() as batch:
|
||||
for d in docs_to_load:
|
||||
with open(os.path.join("knowledge", d), "r") as f:
|
||||
content = f.read()
|
||||
batch.add_object(
|
||||
{
|
||||
"content": content,
|
||||
"year": d.split("_")[0],
|
||||
}
|
||||
)
|
||||
|
||||
# Inicializar a ferramenta
|
||||
tool = WeaviateVectorSearchTool(
|
||||
collection_name='example_collections',
|
||||
limit=3,
|
||||
weaviate_cluster_url="https://your-weaviate-cluster-url.com",
|
||||
weaviate_api_key="your-weaviate-api-key",
|
||||
)
|
||||
```
|
||||
|
||||
## Exemplo de Integração com Agente
|
||||
|
||||
Veja como integrar o `WeaviateVectorSearchTool` com um agente CrewAI:
|
||||
|
||||
```python Code
|
||||
from crewai import Agent
|
||||
from crewai_tools import WeaviateVectorSearchTool
|
||||
|
||||
# Inicializar a ferramenta
|
||||
weaviate_tool = WeaviateVectorSearchTool(
|
||||
collection_name='example_collections',
|
||||
limit=3,
|
||||
weaviate_cluster_url="https://your-weaviate-cluster-url.com",
|
||||
weaviate_api_key="your-weaviate-api-key",
|
||||
)
|
||||
|
||||
# Criar um agente com a ferramenta
|
||||
rag_agent = Agent(
|
||||
name="rag_agent",
|
||||
role="Você é um assistente útil que pode responder perguntas com a ajuda do WeaviateVectorSearchTool.",
|
||||
llm="gpt-4o-mini",
|
||||
tools=[weaviate_tool],
|
||||
)
|
||||
```
|
||||
|
||||
## Conclusão
|
||||
|
||||
O `WeaviateVectorSearchTool` fornece uma maneira poderosa de buscar documentos semanticamente similares em um banco de dados vetorial Weaviate. Ao utilizar embeddings vetoriais, ele permite resultados de busca mais precisos e relevantes em termos de contexto, quando comparado a buscas tradicionais baseadas em palavras-chave. Essa ferramenta é especialmente útil para aplicações que precisam encontrar informações a partir do significado e não apenas de correspondências exatas.
|
||||
Reference in New Issue
Block a user