Laboratório: Pipeline de Busca Semântica e QA com Haystack, Elasticsearch e FAISS

Roteiro para estudo em ambiente de laboratório ou de teste. Execute apenas em equipamentos, redes e contas que você tenha autorização para usar, com backup e homologação próprios. Comandos podem causar indisponibilidade ou perda de dados. Software e marcas citados pertencem aos seus titulares. Termos de Uso.

Duração estimada

120 min

Passos

11

Validações

4

Versões da documentação consultada

Haystack a versão estável atual · Elasticsearch 8.x · FAISS a versão estável atual · Docker a versão estável atual · Python 3.10 ou superior

Topologia

O usuário acessa o pipeline Haystack via REST API (localhost:8000). O Haystack conecta-se ao Elasticsearch (localhost:9200) para indexação textual e ao FAISS (em disco local) para busca vetorial. Todos os serviços rodam em uma única máquina (exemplo: 192.168.56.10).

Usuário HTTP
     |
     v
Haystack API (localhost:8000)
     |
  +--+-------------+
  |                |
  v                v
Elasticsearch   FAISS (local)
(localhost:9200) (em disco)

Equipamentos e software

Roteiro

1. Preparar ambiente e dependências

   Garanta um sistema limpo, atualizado e com Docker, Python 3.10+ e pip instalados. Isso evita conflitos e facilita o gerenciamento dos serviços.

   sudo apt update && sudo apt install -y docker.io docker-compose python3 python3-pipCopiar

   O que você deve ver: Docker, Docker Compose e Python instalados sem erros.

2. Subir Elasticsearch via Docker

   Elasticsearch é necessário para indexação e busca textual. Usar Docker simplifica a instalação e isolamento.

   docker run -d --name elasticsearch -e "discovery.type=single-node" -p 9200:9200 docker.elastic.co/elasticsearch/elasticsearch:8.13.4Copiar

   O que você deve ver: Container 'elasticsearch' rodando. Porta 9200 aberta.

3. Testar Elasticsearch

   Confirme que o Elasticsearch está acessível e pronto.

   curl -X GET 'localhost:9200/'Copiar

   O que você deve ver: Resposta JSON com 'cluster_name' e 'tagline'.

4. Instalar Haystack e FAISS

   Haystack orquestra todo o pipeline. FAISS é o backend vetorial para busca semântica. Instale ambos no Python.

   pip3 install farm-haystack[faiss]Copiar

   O que você deve ver: Pacotes instalados sem erros.

5. Baixar modelo de embeddings

   O modelo de embeddings converte texto em vetores. Usar um modelo aberto garante reprodutibilidade.

   python3 -c "from haystack.utils import fetch_archive_from_http; fetch_archive_from_http(url='https://public.ukp.informatik.tu-darmstadt.de/reimers/sentence-transformers/v0.2/all-MiniLM-L6-v2.zip', output_dir='.')"Copiar

   O que você deve ver: Arquivo do modelo baixado e descompactado.

6. Criar script de pipeline Haystack

   Monte um pipeline simples com DocumentStore FAISS, Retriever e Reader. O script conecta ao Elasticsearch e FAISS.

   cat > haystack_lab.py <<'EOF'
   from haystack.document_stores import FAISSDocumentStore
   from haystack.nodes import EmbeddingRetriever, FARMReader
   from haystack.pipelines import ExtractiveQAPipeline
   from haystack.utils import clean_wiki_text, convert_files_to_docs, fetch_archive_from_http
   
   doc_store = FAISSDocumentStore(faiss_index_factory_str="Flat", sql_url="sqlite:///faiss_lab.db")
   retriever = EmbeddingRetriever(document_store=doc_store, embedding_model="sentence-transformers/all-MiniLM-L6-v2")
   reader = FARMReader(model_name_or_path="deepset/roberta-base-squad2")
   pipeline = ExtractiveQAPipeline(reader, retriever)
   
   # Indexar documentos de exemplo
   docs = [{"content": "A rede de fibra dedicada da Upnetix cobre toda a zona industrial de Manaus."},
           {"content": "Haystack permite implementar pipelines de perguntas e respostas com modelos abertos."}]
   doc_store.write_documents(docs)
   doc_store.update_embeddings(retriever)
   
   # Testar pipeline
   prediction = pipeline.run(query="Quem cobre a zona industrial de Manaus?", params={"Retriever": {"top_k": 2}, "Reader": {"top_k": 1}})
   print(prediction)
   EOFCopiar

   O que você deve ver: Arquivo haystack_lab.py criado com pipeline funcional.

7. Executar pipeline localmente

   Rode o script para garantir que o pipeline está funcionando e retornando respostas.

   python3 haystack_lab.pyCopiar

   O que você deve ver: Saída JSON com resposta à pergunta e contexto do documento.

8. Subir API REST do Haystack

   Haystack oferece API REST para integração. Use o comando oficial para expor o pipeline.

   pip3 install uvicorn fastapi
   haystack server startCopiar

   O que você deve ver: Servidor iniciado em http://localhost:8000.

9. Testar API REST com curl

   Valide o endpoint enviando uma pergunta para o pipeline via HTTP.

   curl -X POST 'http://localhost:8000/query' -H 'Content-Type: application/json' -d '{"query": "O que é Haystack?"}'Copiar

   O que você deve ver: Resposta JSON com resposta extraída dos documentos.

10. Indexar novos documentos via API

    Garanta que é possível adicionar documentos dinamicamente pelo endpoint.

    curl -X POST 'http://localhost:8000/documents' -H 'Content-Type: application/json' -d '{"documents": [{"content": "FAISS é uma biblioteca eficiente para busca vetorial."}]}'Copiar

    O que você deve ver: Confirmação de indexação sem erro.

11. Consultar novamente após indexação

    Teste se o novo conteúdo é recuperado pelo pipeline.

    curl -X POST 'http://localhost:8000/query' -H 'Content-Type: application/json' -d '{"query": "O que é FAISS?"}'Copiar

    O que você deve ver: Resposta contendo 'FAISS é uma biblioteca eficiente para busca vetorial.'

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Nunca exponha Elasticsearch ou API Haystack sem autenticação em redes públicas.
• Utilize firewall para restringir acesso às portas 9200 e 8000.
• Remova documentos sensíveis após testes.
• Atualize todos os componentes antes de uso produtivo.

Checklist final

• Elasticsearch acessível em localhost:9200
• FAISS instalado e funcional
• Pipeline Haystack executando localmente
• API REST do Haystack disponível em localhost:8000
• Consulta retorna respostas relevantes
• Indexação dinâmica via API testada