Introdução ao Dify

O Dify é uma plataforma de desenvolvimento de aplicativos de LLM (Large Language Model) de código aberto e fácil utilização. Seu objetivo é simplificar a criação de soluções baseadas em inteligência artificial, abstraindo a complexidade da infraestrutura subjacente.

• Suporte a múltiplos provedores e modelos de LLM.
• Gerenciamento nativo de bases de conhecimento (RAG).
• Disponibilização de APIs para integração externa.
• Capacidade de implantação local, garantindo privacidade e segurança dos dados.

Pré-requisitos e Instalação

1. Preparação do Ambiente

Antes de iniciar, certifique-se de que as seguintes ferramentas estão instaladas no seu macOS:

• Docker e Docker Compose
• Git
• Ollama (certifique-se de baixar o modelo de embeddings nomic-embed-text:latest)
• Chave de API (API Key) para o modelo DeepSeek-R1 ou outro LLM de sua preferência

2. Deploy do Dify

Clonando o repositório:

git clone https://github.com/langgenius/dify.git dify-local
cd dify-local/docker

Configuração e inicialização dos containers:

# Copiar o arquivo de variáveis de ambiente
cp .env.example .env

# Subir os serviços em modo background
docker compose up -d

# Verificar o status dos containers
docker ps --filter "name=docker"

Após a inicialização, acesse a interface web através do endereço http://localhost/install para criar a conta de administrador inicial. As credenciais serão armazenadas localmente no banco de dados da aplicação.

Configuração e Uso da Plataforma

1. Integração de Modelos

Navegue até as configurações de provedores de modelos para adicionar e habilitar os LLMs e modelos de embeddings:

• Modelo de LLM: Configure a API do DeepSeek ou conecte o Ollama local.
• Modelo de Embedding: Selecione o nomic-embed-text rodando via Ollama para processamento vetorial dos documentos.

2. Criação da Base de Conhecimento

1. Ingestão de Dados: Faça o upload dos seus documentos (PDF, TXT, Markdown, etc.).
2. Processamento: Defina as regras de segmentação (chunking) e limpe o texto.
3. Indexação: Aguarde a conclusão do processo de vetorialização.
4. Validação: Revise os chunks gerados na interface de detalhes do documento.

3. Desenvolvimento do Chatbot

Para criar um assistente virtual baseado na sua base de conhecimento:

1. Criação: Defina um nome para o seu aplicativo do tipo "Chatbot".
2. Prompt Engineering: Escreva as instruções do sistema (System Prompt) e vincule a base de conhecimento criada anteriormente. Aplique as alterações.
3. Testes: Utilize o painel de depuração para interagir com o bot e ajustar o contexto.
4. Publicação: Clique em "Publish" para tornar o aplicativo ativo.

O Dify oferece múltiplas formas de acessar o bot publicado:

• Interface Web nativa (Web App).
• Incorporação via iframe ou script em páginas HTML.
• Extensões para navegadores.
• Integração via API REST.

4. Integração via API Externa

Para consumir o chatbot programaticamente, gere uma chave de API nas configurações do aplicativo e utilize requisições HTTP:

curl -X POST 'http://localhost/v1/chat-messages' \
  -H 'Authorization: Bearer app-XyZ987AbCdEfGhIjKlMnOpQr' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "inputs": {},
    "query": "Forneça um resumo do livro Dom Casmurro, incluindo autor e ano de publicação no formato JSON.",
    "response_mode": "blocking",
    "conversation_id": "",
    "user": "user-system-001",
    "files": []
  }'

Resolução de Problemas Comuns

Falha de Autenticação e Redefinição de Senha

Se você perder a senha do administrador, execute o script de redefinição dentro do container da API:

docker exec -it docker-api-1 flask reset-password

Em casos de bloqueio por múltiplas tentativas incorretas, pode ser necessário limpar o cache do Redis:

docker exec -it docker-redis-1 redis-cli
# Dentro do CLI do Redis:
> KEYS *login*
> DEL nome_da_chave_específica

Conflito de Portas (Ex: 5432 ou 6379)

Se o PostgreSQL ou Redis falharem ao iniciar devido a portas em uso no host, identifique e encerre os processos conflitantes:

# Identificar o PID do processo na porta 5432
lsof -i :5432

# Encerrar o processo
kill -9 <PID>

Falha de Conexão com o Ollama Local

Como o Dify é executado dentro de containers Docker, ele não consegue resolver localhost para acessar serviços rodando no sistema host (como o Ollama).

Solução: Ao configurar a URL do Ollama na interface do Dify, utilize o endereço especial do Docker para o host:

http://host.docker.internal:11434