├── .gitignore ├── LICENSE ├── README.md └── app.py /.gitignore: -------------------------------------------------------------------------------- 1 | # Byte-compiled / optimized / DLL files 2 | __pycache__/ 3 | *.py[cod] 4 | *$py.class 5 | 6 | # C extensions 7 | *.so 8 | 9 | # Distribution / packaging 10 | .Python 11 | build/ 12 | develop-eggs/ 13 | dist/ 14 | downloads/ 15 | eggs/ 16 | .eggs/ 17 | lib/ 18 | lib64/ 19 | parts/ 20 | sdist/ 21 | var/ 22 | wheels/ 23 | share/python-wheels/ 24 | *.egg-info/ 25 | .installed.cfg 26 | *.egg 27 | MANIFEST 28 | 29 | # PyInstaller 30 | # Usually these files are written by a python script from a template 31 | # before PyInstaller builds the exe, so as to inject date/other infos into it. 32 | *.manifest 33 | *.spec 34 | 35 | # Installer logs 36 | pip-log.txt 37 | pip-delete-this-directory.txt 38 | 39 | # Unit test / coverage reports 40 | htmlcov/ 41 | .tox/ 42 | .nox/ 43 | .coverage 44 | .coverage.* 45 | .cache 46 | nosetests.xml 47 | coverage.xml 48 | *.cover 49 | *.py,cover 50 | .hypothesis/ 51 | .pytest_cache/ 52 | cover/ 53 | 54 | # Translations 55 | *.mo 56 | *.pot 57 | 58 | # Django stuff: 59 | *.log 60 | local_settings.py 61 | db.sqlite3 62 | db.sqlite3-journal 63 | 64 | # Flask stuff: 65 | instance/ 66 | .webassets-cache 67 | 68 | # Scrapy stuff: 69 | .scrapy 70 | 71 | # Sphinx documentation 72 | docs/_build/ 73 | 74 | # PyBuilder 75 | .pybuilder/ 76 | target/ 77 | 78 | # Jupyter Notebook 79 | .ipynb_checkpoints 80 | 81 | # IPython 82 | profile_default/ 83 | ipython_config.py 84 | 85 | # pyenv 86 | # For a library or package, you might want to ignore these files since the code is 87 | # intended to run in multiple environments; otherwise, check them in: 88 | # .python-version 89 | 90 | # pipenv 91 | # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. 92 | # However, in case of collaboration, if having platform-specific dependencies or dependencies 93 | # having no cross-platform support, pipenv may install dependencies that don't work, or not 94 | # install all needed dependencies. 95 | #Pipfile.lock 96 | 97 | # UV 98 | # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control. 99 | # This is especially recommended for binary packages to ensure reproducibility, and is more 100 | # commonly ignored for libraries. 101 | #uv.lock 102 | 103 | # poetry 104 | # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. 105 | # This is especially recommended for binary packages to ensure reproducibility, and is more 106 | # commonly ignored for libraries. 107 | # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control 108 | #poetry.lock 109 | 110 | # pdm 111 | # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. 112 | #pdm.lock 113 | # pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it 114 | # in version control. 115 | # https://pdm.fming.dev/latest/usage/project/#working-with-version-control 116 | .pdm.toml 117 | .pdm-python 118 | .pdm-build/ 119 | 120 | # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm 121 | __pypackages__/ 122 | 123 | # Celery stuff 124 | celerybeat-schedule 125 | celerybeat.pid 126 | 127 | # SageMath parsed files 128 | *.sage.py 129 | 130 | # Environments 131 | .env 132 | .venv 133 | env/ 134 | venv/ 135 | ENV/ 136 | env.bak/ 137 | venv.bak/ 138 | 139 | # Spyder project settings 140 | .spyderproject 141 | .spyproject 142 | 143 | # Rope project settings 144 | .ropeproject 145 | 146 | # mkdocs documentation 147 | /site 148 | 149 | # mypy 150 | .mypy_cache/ 151 | .dmypy.json 152 | dmypy.json 153 | 154 | # Pyre type checker 155 | .pyre/ 156 | 157 | # pytype static type analyzer 158 | .pytype/ 159 | 160 | # Cython debug symbols 161 | cython_debug/ 162 | 163 | # PyCharm 164 | # JetBrains specific template is maintained in a separate JetBrains.gitignore that can 165 | # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore 166 | # and can be added to the global gitignore or merged into this file. For a more nuclear 167 | # option (not recommended) you can uncomment the following to ignore the entire idea folder. 168 | #.idea/ 169 | 170 | # PyPI configuration file 171 | .pypirc 172 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2025 Asimov Academy 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # RAG 2 | 3 | Este documento explica, passo a passo, como funciona o script que realiza a seguinte tarefa: 4 | - Carrega arquivos Markdown de um diretório. 5 | - Processa esses arquivos para gerar embeddings (vetores numéricos) utilizando a API do OpenAI. 6 | - Indexa esses embeddings com FAISS para realizar buscas semânticas eficientes. 7 | - Configura um agente conversacional (RAG) que utiliza os documentos indexados para responder perguntas do usuário. 8 | 9 | Além disso, esta documentação detalha como configurar o ambiente, incluindo a criação do arquivo `.env` na raiz do projeto para armazenar variáveis sensíveis (por exemplo, a chave da API do OpenAI). 10 | 11 | --- 12 | 13 | ## 1. Requisitos e Dependências 14 | 15 | Para executar este script, você precisará ter instaladas as seguintes bibliotecas (com as versões indicadas): 16 | 17 | - **Python:** `^3.12` 18 | - **streamlit:** `^1.42.0` 19 | - **langchain:** `^0.3.18` 20 | - **langchain-openai:** `^0.3.5` 21 | - **python-dotenv:** `^1.0.1` 22 | - **langchain-community:** `0.3.16` 23 | - **numpy:** `^1.23.5` 24 | - **unstructured:** `^0.16.21` 25 | - **faiss-cpu:** `^1.10.0` 26 | - **openai:** `^1.63.2` 27 | - **markdown:** `^3.7` 28 | - **langchain-cli:** `^0.0.35` 29 | 30 | ### Exemplo de instalação via pip: 31 | 32 | ```bash 33 | pip install python-dotenv streamlit langchain langchain-openai langchain-community numpy unstructured faiss-cpu openai markdown langchain-cli 34 | ``` 35 | 36 | --- 37 | 38 | ## 2. Configuração do Arquivo de Ambiente (.env) 39 | 40 | Para garantir que o script funcione corretamente, é necessário criar um arquivo de ambiente chamado `.env` na raiz do projeto. Esse arquivo armazenará variáveis sensíveis, como a chave de API do OpenAI, sem que elas fiquem diretamente no código-fonte. 41 | 42 | ### Passos para criar e configurar o arquivo `.env`: 43 | 44 | 1. **Crie o arquivo:** 45 | - Na raiz do seu projeto (ou seja, no mesmo diretório onde está o script Python), crie um novo arquivo com o nome: 46 | ``` 47 | .env 48 | ``` 49 | 50 | 2. **Defina as variáveis de ambiente:** 51 | - Abra o arquivo `.env` em um editor de texto e adicione a(s) variável(is) necessárias. Por exemplo, para a chave da API do OpenAI, adicione: 52 | ```env 53 | OPENAI_API_KEY=your-api-key-aqui 54 | ``` 55 | - Substitua `your-api-key-aqui` pela sua chave real da API do OpenAI. 56 | 57 | 3. **Utilização no Script:** 58 | - No início do script, a biblioteca `python-dotenv` é utilizada para carregar essas variáveis: 59 | ```python 60 | from dotenv import load_dotenv 61 | load_dotenv() 62 | ``` 63 | - Assim, a variável `OPENAI_API_KEY` (ou outras que você definir) estará disponível para uso no script sem precisar codificá-la diretamente. 64 | 65 | --- 66 | 67 | ## 3. Estrutura do Script 68 | 69 | A seguir, uma explicação detalhada de cada parte do script. 70 | 71 | ### 3.1 Configuração Inicial e Importação das Dependências 72 | 73 | **Objetivo:** 74 | Carregar as variáveis de ambiente e importar as bibliotecas necessárias para: 75 | - Carregar e processar os arquivos Markdown. 76 | - Gerar embeddings via OpenAI. 77 | - Indexar os embeddings com FAISS. 78 | - Configurar o agente conversacional para interação. 79 | 80 | **Código:** 81 | 82 | ```python 83 | from dotenv import load_dotenv # Carrega variáveis de ambiente do arquivo .env 84 | from langchain_community.document_loaders import DirectoryLoader # Carrega arquivos de um diretório 85 | from langchain_community.document_loaders import UnstructuredMarkdownLoader # Processa arquivos Markdown 86 | from langchain_openai.embeddings import OpenAIEmbeddings # Converte textos em vetores utilizando a API do OpenAI 87 | from langchain_community.vectorstores import FAISS # Cria um índice vetorial para busca semântica 88 | from langchain.chains.conversational_retrieval.base import ConversationalRetrievalChain # Combina recuperação de documentos e conversação 89 | from langchain_openai.chat_models import ChatOpenAI # Modelo de chat baseado na API do OpenAI 90 | 91 | # Carrega as variáveis de ambiente definidas no arquivo .env 92 | load_dotenv() 93 | ``` 94 | 95 | ### 3.2 Carregamento dos Documentos Markdown 96 | 97 | **Objetivo:** 98 | Localizar e carregar recursivamente arquivos Markdown a partir de um diretório especificado. 99 | 100 | **Código:** 101 | 102 | ```python 103 | # Define o caminho para a pasta que contém os arquivos Markdown 104 | pasta_dos_md = r"/home/samuel/Samuel Sublate/" # Atualize conforme a localização dos seus arquivos 105 | 106 | # Cria um DirectoryLoader para buscar recursivamente por arquivos .md 107 | loader = DirectoryLoader( 108 | pasta_dos_md, 109 | glob="**/*.md", # Padrão que abrange todos os arquivos com extensão .md, inclusive em subdiretórios 110 | loader_cls=UnstructuredMarkdownLoader # Processa cada arquivo Markdown 111 | ) 112 | 113 | # Carrega os documentos encontrados e armazena na variável 'docs' 114 | docs = loader.load() 115 | print(f"{len(docs)} arquivos Markdown carregados.") 116 | ``` 117 | 118 | **Detalhes Importantes:** 119 | - **pasta_dos_md:** Caminho absoluto ou relativo para o diretório onde os arquivos Markdown estão armazenados. 120 | - **DirectoryLoader:** Realiza uma busca recursiva com base no padrão definido (`**/*.md`). 121 | - **UnstructuredMarkdownLoader:** Lida com a formatação dos arquivos Markdown, extraindo o conteúdo textual. 122 | 123 | ### 3.3 Criação do Índice Vetorial (Embeddings e FAISS) 124 | 125 | **Objetivo:** 126 | Converter o conteúdo dos documentos em embeddings e indexá-los com FAISS para buscas semânticas. 127 | 128 | **Código:** 129 | 130 | ```python 131 | # Cria embeddings dos documentos utilizando a API do OpenAI 132 | embeddings = OpenAIEmbeddings() 133 | 134 | # Indexa os documentos com FAISS para realizar buscas eficientes 135 | vector_store = FAISS.from_documents(docs, embeddings) 136 | ``` 137 | 138 | **Detalhes Importantes:** 139 | - **OpenAIEmbeddings:** Responsável por transformar textos em vetores numéricos, permitindo a comparação semântica. 140 | - **FAISS:** Biblioteca de indexação vetorial que facilita a busca dos documentos mais relevantes para uma dada consulta. 141 | 142 | ### 3.4 Configuração do Agente Conversacional (RAG) 143 | 144 | **Objetivo:** 145 | Integrar o modelo de chat com o mecanismo de recuperação de documentos para responder às perguntas do usuário. 146 | 147 | **Código:** 148 | 149 | ```python 150 | # Inicializa o modelo de chat do OpenAI com temperatura 0 para respostas determinísticas 151 | chat_model = ChatOpenAI(temperature=0) 152 | 153 | # Cria uma cadeia conversacional que utiliza o modelo de chat e o índice FAISS para recuperação de documentos 154 | qa_chain = ConversationalRetrievalChain.from_llm( 155 | llm=chat_model, 156 | retriever=vector_store.as_retriever(), 157 | ) 158 | ``` 159 | 160 | **Detalhes Importantes:** 161 | - **ChatOpenAI:** Configurado com uma temperatura baixa para garantir respostas mais consistentes. 162 | - **ConversationalRetrievalChain:** Combina a capacidade do modelo de linguagem com a busca nos documentos indexados, possibilitando respostas fundamentadas no conteúdo dos Markdown. 163 | 164 | ### 3.5 Interação com o Usuário 165 | 166 | **Objetivo:** 167 | Permitir a interação via terminal, onde o usuário envia uma consulta e recebe a resposta do agente. 168 | 169 | **Código:** 170 | 171 | ```python 172 | print("Converse com o agente (digite 'sair' para encerrar):") 173 | while True: 174 | print('\n') 175 | # Recebe a consulta do usuário via terminal 176 | query = input("Você:") 177 | 178 | # Encerra o loop se o usuário digitar 'sair', 'exit' ou 'quit' 179 | if query.lower() in ["sair", "exit", "quit"]: 180 | break 181 | 182 | # Envia a consulta e um histórico de conversa vazio para a cadeia conversacional 183 | result = qa_chain({"question": query, "chat_history": []}) 184 | print('\n') 185 | # Exibe a resposta gerada pelo agente 186 | print("Agente:", result["answer"]) 187 | ``` 188 | 189 | **Detalhes Importantes:** 190 | - **Loop Interativo:** Permite múltiplas interações até que o usuário opte por sair. 191 | - **chat_history:** Inicialmente é uma lista vazia. Em aplicações avançadas, pode ser utilizada para manter o contexto da conversa. 192 | 193 | --- 194 | 195 | ## 4. Estrutura do Projeto 196 | 197 | Uma estrutura básica do projeto pode ser semelhante a esta: 198 | 199 | ``` 200 | meu_projeto/ 201 | ├── .env 202 | ├── script.py 203 | └── README.md 204 | ``` 205 | 206 | - **.env:** Arquivo de configuração com variáveis de ambiente. 207 | - **script.py:** Contém o código do script explicado nesta documentação. 208 | - **README.md:** Este arquivo de documentação. 209 | 210 | --- 211 | 212 | ## 5. Conclusão 213 | 214 | Este script integra diversas tecnologias para transformar documentos Markdown em uma base de conhecimento consultável através de um agente conversacional. Através das etapas de: 215 | - Configuração do ambiente (usando um arquivo `.env`), 216 | - Carregamento e processamento dos arquivos Markdown, 217 | - Criação de embeddings e indexação com FAISS, 218 | - Configuração do agente conversacional (RAG) e 219 | - Interação via terminal, 220 | 221 | você pode criar uma aplicação robusta que responde perguntas com base no conteúdo dos seus documentos. 222 | 223 | Certifique-se de: 224 | 1. **Criar e configurar o arquivo `.env`** na raiz do projeto com as variáveis necessárias (por exemplo, `OPENAI_API_KEY`). 225 | 2. **Instalar as dependências** com as versões recomendadas. 226 | 3. **Ajustar os caminhos** e demais configurações conforme a estrutura do seu ambiente. 227 | 228 | Experimente, teste e expanda o script conforme suas necessidades! 229 | 230 | --- 231 | -------------------------------------------------------------------------------- /app.py: -------------------------------------------------------------------------------- 1 | # Configuração Inicial e Importação das Dependências 2 | from dotenv import load_dotenv # Carrega variáveis de ambiente a partir de um arquivo .env 3 | from langchain_community.document_loaders import DirectoryLoader # Carrega arquivos de um diretório 4 | from langchain_community.document_loaders import UnstructuredMarkdownLoader # Processa arquivos Markdown 5 | from langchain_openai.embeddings import OpenAIEmbeddings # Converte textos em vetores (embeddings) usando a API do OpenAI 6 | from langchain_community.vectorstores import FAISS # Cria um índice vetorial para busca eficiente 7 | from langchain.chains.conversational_retrieval.base import ConversationalRetrievalChain # Combina recuperação de documentos e conversação 8 | from langchain_openai.chat_models import ChatOpenAI # Modelo de chat baseado na API do OpenAI 9 | 10 | # Carrega as variáveis de ambiente do arquivo .env (ex.: chave da API do OpenAI) 11 | load_dotenv() 12 | 13 | # Carregamento dos Documentos Markdown 14 | # Define o caminho para a pasta que contém os arquivos Markdown 15 | pasta_dos_md = r"/home/samuel/Samuel Sublate/" # Atualize este caminho conforme necessário 16 | 17 | # Cria uma instância do DirectoryLoader para buscar recursivamente arquivos .md no diretório 18 | loader = DirectoryLoader( 19 | pasta_dos_md, 20 | glob="**/*.md", # Padrão que busca todos os arquivos com extensão .md, inclusive em subdiretórios 21 | loader_cls=UnstructuredMarkdownLoader # Utiliza o UnstructuredMarkdownLoader para processar cada arquivo Markdown 22 | ) 23 | 24 | # Carrega os documentos encontrados e armazena na variável 'docs' 25 | docs = loader.load() 26 | print(f"{len(docs)} arquivos Markdown carregados.") 27 | 28 | # Criação do Índice Vetorial (Embeddings e FAISS) 29 | # Converte o texto dos documentos em vetores numéricos (embeddings) usando a API do OpenAI 30 | embeddings = OpenAIEmbeddings() 31 | 32 | # Cria um índice vetorial com FAISS utilizando os documentos e seus embeddings 33 | vector_store = FAISS.from_documents(docs, embeddings) 34 | 35 | # Configuração do Agente Conversacional (RAG) 36 | # Instancia o modelo de chat do OpenAI com temperatura 0 para respostas mais determinísticas 37 | chat_model = ChatOpenAI(temperature=0) 38 | 39 | # Cria a cadeia conversacional que integra o modelo de chat com o mecanismo de recuperação de documentos (retriever) 40 | # O retriever é gerado a partir do índice FAISS (vector_store) 41 | qa_chain = ConversationalRetrievalChain.from_llm( 42 | llm=chat_model, 43 | retriever=vector_store.as_retriever(), 44 | ) 45 | 46 | # Interação com o Usuário e Exibição das Respostas 47 | print("Converse com o agente (digite 'sair' para encerrar):") 48 | while True: 49 | print('\n') 50 | # Recebe a consulta do usuário via terminal 51 | query = input("Você:") 52 | 53 | # Se o usuário digitar 'sair', 'exit' ou 'quit', encerra o loop e finaliza a aplicação 54 | if query.lower() in ["sair", "exit", "quit"]: 55 | break 56 | 57 | # Envia a consulta e um histórico de conversa vazio (lista) para a cadeia conversacional (para a primeira interação) 58 | result = qa_chain({"question": query, "chat_history": []}) 59 | print('\n') 60 | # Exibe a resposta gerada pelo agente 61 | print("Agente:", result["answer"]) 62 | --------------------------------------------------------------------------------