Hugging Face's logo

Spaces:
guifav
/
rag_template
Sleeping

App Files Community
rag_template / docs /SPACES_SECRETS.md
Guilherme Favaron
Sync: Complete project update (Phase 6) - API, Metadata, Eval, Docs
a686b1b
preview code
|
raw
history blame contribute delete
6.86 kB

A newer version of the Gradio SDK is available: 6.5.1

Upgrade

Secrets para Hugging Face Spaces

Guia completo para configurar secrets no Hugging Face Spaces para o RAG Template.

Como Configurar Secrets

  1. Acesse seu Space no Hugging Face
  2. Va para Settings
  3. Role ate a secao Repository secrets
  4. Clique em New secret para cada secret necessario
  5. Adicione nome e valor
  6. Clique em Add secret

Secrets Obrigatorios

DATABASE_URL

Obrigatorio: Sim

Connection string do PostgreSQL com pgvector.

Formato:

postgresql://user:password@host:port/database

Exemplos:

# Supabase
postgresql://postgres:sua_senha@db.xxxxxxxxxxxxx.supabase.co:5432/postgres

# Neon
postgresql://user:senha@ep-xxx-xxx.us-east-1.aws.neon.tech/neondb?sslmode=require

# Railway
postgresql://postgres:senha@containers-us-west-xxx.railway.app:5432/railway

Importante:

  • Certifique-se de que a senha esta URL-encoded se conter caracteres especiais
  • Para Neon, inclua ?sslmode=require
  • Teste a conexao antes de adicionar ao Space

Como obter:

Secrets de LLM Providers

Voce precisa de pelo menos um destes para usar o chat:

HF_TOKEN (Recomendado para Spaces)

Obrigatorio: Nao, mas recomendado

Token da Hugging Face para usar Inference API.

Como obter:

  1. Va para huggingface.co/settings/tokens
  2. Crie novo token com permissao "read"
  3. Copie o token

Formato:

hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Vantagens:

  • Gratuito (com limites)
  • Sem necessidade de infraestrutura
  • Varios modelos disponiveis

Limites Free Tier:

  • ~30k tokens/hora
  • Pode ter queue em horarios de pico

OPENAI_API_KEY

Obrigatorio: Nao

Chave de API da OpenAI para usar GPT-4, GPT-3.5, etc.

Como obter:

  1. Crie conta em platform.openai.com
  2. Va para API Keys
  3. Crie nova secret key
  4. Copie a chave (aparece apenas uma vez!)

Formato:

sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Custos (Fevereiro 2024):

  • GPT-3.5-turbo: $0.50 / 1M tokens input
  • GPT-4-turbo: $10 / 1M tokens input
  • GPT-4o: $5 / 1M tokens input

ANTHROPIC_API_KEY

Obrigatorio: Nao

Chave de API da Anthropic para usar Claude.

Como obter:

  1. Crie conta em console.anthropic.com
  2. Va para API Keys
  3. Crie nova key
  4. Copie a chave

Formato:

sk-ant-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Custos (Fevereiro 2024):

  • Claude 3 Haiku: $0.25 / 1M tokens input
  • Claude 3 Sonnet: $3 / 1M tokens input
  • Claude 3 Opus: $15 / 1M tokens input

OLLAMA_BASE_URL

Obrigatorio: Nao

URL do servidor Ollama para usar modelos locais.

Como configurar:

  1. Instale Ollama localmente ou em servidor
  2. Exponha via ngrok ou similar (para Spaces)
  3. Use URL publica

Formato:

https://seu-servidor.com

Nota: Nao recomendado para Spaces publicos (requer servidor proprio).

Secrets Opcionais

EMBEDDING_MODEL_ID

Default: sentence-transformers/all-MiniLM-L6-v2

Modelo para gerar embeddings.

Alternativas:

sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2  # Multilingue
sentence-transformers/all-mpnet-base-v2  # Melhor qualidade (768d)
BAAI/bge-small-en-v1.5  # Eficiente

TOP_K

Default: 4

Numero de documentos a recuperar na busca.

Range: 1-20

TEMPERATURE

Default: 0.3

Criatividade do LLM (0 = deterministico, 1 = criativo).

Range: 0.0-1.0

MAX_TOKENS

Default: 512

Tamanho maximo da resposta do LLM.

Range: 100-4096

Exemplo Completo 

# Obrigatorio
DATABASE_URL=postgresql://postgres:senha@db.xxx.supabase.co:5432/postgres

# LLM (escolha pelo menos um)
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxx

# Opcional
EMBEDDING_MODEL_ID=sentence-transformers/all-MiniLM-L6-v2
TOP_K=4
TEMPERATURE=0.3
MAX_TOKENS=512

Validacao de Secrets

Apos configurar, o app validara os secrets na inicializacao:

Validacoes:

  1. DATABASE_URL: Testa conexao e verifica extensao pgvector
  2. HF_TOKEN: Testa autenticacao (se fornecido)
  3. OPENAI_API_KEY: Testa autenticacao (se fornecido)
  4. ANTHROPIC_API_KEY: Testa autenticacao (se fornecido)

Logs de inicializacao: 

Conectando ao banco de dados...
  DATABASE_URL: OK
  Extensao pgvector: OK
Verificando LLM providers...
  HuggingFace: OK
  OpenAI: NAO CONFIGURADO
  Anthropic: NAO CONFIGURADO

Seguranca

Boas Praticas:

  1. Nunca compartilhe secrets publicamente

    • Nao commite no Git
    • Nao coloque em codigo
    • Nao compartilhe em issues/forums

  2. Rotacao de secrets

    • Troque secrets periodicamente
    • Revogue secrets antigos
    • Use secrets separados para dev/prod

  3. Principio do menor privilegio

    • Use apenas permissoes necessarias
    • Para HF_TOKEN, permissao "read" e suficiente
    • Nao use tokens com permissoes de "write"

  4. Monitoring

    • Monitore uso de API keys
    • Configure alerts de uso anormal
    • Revogue imediatamente se comprometido

Troubleshooting

"Unable to connect to database"

Causa: DATABASE_URL incorreto ou banco inacessivel

Solucao:

  1. Verifique formato da URL
  2. Teste conexao localmente
  3. Verifique se banco esta ativo (Supabase nao pausado)

"HF_TOKEN invalid"

Causa: Token invalido ou expirado

Solucao:

  1. Gere novo token em huggingface.co/settings/tokens
  2. Certifique-se de copiar token completo
  3. Token deve comecar com hf_

"OpenAI authentication failed"

Causa: OPENAI_API_KEY invalida

Solucao:

  1. Verifique se key e valida em platform.openai.com
  2. Certifique-se de ter creditos na conta
  3. Key deve comecar com sk-

"Extension 'vector' not found"

Causa: pgvector nao habilitado no banco

Solucao:

-- Execute no SQL Editor do seu provider
CREATE EXTENSION vector;

Limitacoes do Free Tier

Hugging Face Spaces

  • Secrets podem ser vistos por administradores do Space
  • Spaces publicos podem ter limite de uso
  • Cold start pode demorar

LLM Providers

  • HuggingFace: ~30k tokens/hora
  • OpenAI: Requer creditos ($5 minimo inicial)
  • Anthropic: Requer creditos ($5 minimo inicial)

Recursos Adicionais

Suporte

Se encontrar problemas:

  1. Verifique logs do Space
  2. Teste conexoes localmente
  3. Abra issue no GitHub

Feito com muito cafe