Adicionando guia de acesso remoto e RAG

2026-05-06 14:02:07 -03:00
parent 1da9534dc0
commit cb843b9a88
1 changed files with 52 additions and 0 deletions
@@ -0,0 +1,52 @@
+# Guia de Acesso Externo e Integração de Dados
+
+Este documento descreve como consumir os dados do projeto **apitdn** a partir de qualquer localidade, utilizando a infraestrutura de VPN Mesh (Tailscale) e as interfaces do Gitea.
+
+## 🌐 1. Infraestrutura de Conexão (Tailscale)
+Para acessar o Gitea fora da rede local (192.168.x.x), você deve utilizar o IP atribuído pelo Tailscale ao Raspberry Pi.
+
+*   **Pré-requisito**: A máquina cliente deve estar logada na mesma rede Tailscale.
+*   **IP do Servidor (Exemplo)**: Substitua `192.168.0.63` pelo IP `100.x.x.x` do seu Raspberry Pi no painel do Tailscale.
+
+## 🛠️ 2. Métodos de Consumo de Dados
+
+### A. Clonagem via Git (Ideal para Sincronização)
+Recomendado para baixar toda a base de documentação (~640MB) para processamento local.
+```bash
+git clone http://[IP-TAILSCALE]:3000/rodolpho/apitdn.git
+```
+
+### B. Download de Snapshot (ZIP)
+Ideal para obter uma cópia rápida sem histórico de versões.
+*   **URL**: `http://[IP-TAILSCALE]:3000/rodolpho/apitdn/archive/master.zip`
+
+### C. Acesso Raw (Arquivos Individuais)
+Para leitura direta de um arquivo Markdown específico.
+*   **URL**: `http://[IP-TAILSCALE]:3000/rodolpho/apitdn/raw/branch/master/[CAMINHO_DO_ARQUIVO].md`
+
+## 🤖 3. Integração com LLMs Externas (RAG)
+Se você estiver conectando uma LLM externa (ex: OpenAI, Anthropic) ou um agente de IA à sua rede privada via Tailscale, siga este protocolo:
+
+### Passo 1: Gerar Token de Acesso (PAT)
+Em vez de usar sua senha, gere um token em:
+`Configurações > Aplicativos > Gerar Novo Token`
+
+### Passo 2: Consumo via API REST
+A LLM ou o Agente deve realizar requisições autenticadas para buscar o conteúdo dos arquivos:
+
+**Endpoint de Conteúdo:**
+`GET /api/v1/repos/rodolpho/apitdn/contents/[CAMINHO]`
+
+**Exemplo de Header:**
+```http
+Authorization: token [SEU_TOKEN_PAT]
+Accept: application/json
+```
+
+### Passo 3: Decodificação
+A API retornará o conteúdo em **Base64**. O agente deve decodificar a string para obter o Markdown puro para processamento de contexto.
+
+## 🔒 Segurança
+*   Mantenha o Tailscale ativo no Raspberry Pi.
+*   Nunca exponha a porta 3000 diretamente no roteador sem VPN.
+*   Sempre prefira Tokens de Acesso Pessoal (PAT) com escopo limitado para integrações externas.