Visão geral dos Spaces

Os Hugging Face Spaces facilitam a criação e a implantação de demonstrações com IA em poucos minutos. Assista ao vídeo a seguir para uma introdução rápida aos Spaces:

Nas seções a seguir, você aprenderá os fundamentos para criar um Space, configurá-lo e implantar seu código nele.

Criando um novo Space

Para criar um novo Space, visite a página principal dos Spaces e clique em Criar novo Space. Além de escolher um nome para o seu Space, selecionar uma licença opcional e definir a visibilidade do seu Space (público, protegido ou privado), você será solicitado a escolher o SDK para o seu Space. O Hub oferece três opções de SDK: Gradio, Docker e HTML estático. Se você selecionar “Gradio” como seu SDK, será direcionado a um novo repositório exibindo a seguinte página:

Os Spaces estáticos são gratuitos para todos. Os Spaces Gradio e Docker são executados em compute e exigem um plano pago para serem criados: PRO para contas pessoais, Team ou Enterprise para organizações. Contas pessoais gratuitas em situação regular ainda podem hospedar até 2 Spaces Gradio executados em ZeroGPU.

Por baixo dos panos, o Spaces armazena seu código em um repositório git, assim como os repositórios de modelos e conjuntos de dados. Graças a isso, as mesmas ferramentas que usamos para todos os outros repositórios no Hub (git e git-xet) também funcionam para Spaces. Siga o mesmo fluxo descrito em Getting Started with Repositories para adicionar arquivos ao seu Space. Cada vez que um novo commit é enviado, o Space será reconstruído e reiniciado automaticamente.

Para tutoriais passo a passo sobre como criar seu primeiro Space, consulte os guias abaixo:

• Criando um Espaço Gradio
• Criando um Espaço Docker

Visibilidade do espaço

Você pode definir a visibilidade de um Space na aba Settings usando o menu suspenso de visibilidade. Os Spaces suportam três níveis de visibilidade: public, protected e private.

A visibilidade protegida faz parte dos planos PRO ou Team & Enterprise.

Spaces Públicos são totalmente abertos: qualquer pessoa pode visualizar o código-fonte, acessar o aplicativo em execução e clonar o repositório.

Os Spaces Protegidos mantêm seu código-fonte privado no Hub — apenas o proprietário e os colaboradores podem visualizar ou clonar o repositório. No entanto, o aplicativo em execução é acessível publicamente por meio de sua URL de incorporação (https://<space-subdomain>.hf.space) ou por meio de um domínio personalizado, quando configurado. Isso é especialmente útil para hospedar sites ou aplicativos sem publicar o código-fonte.

Spaces Privados são totalmente privados: o código-fonte e o aplicativo em execução são acessíveis apenas ao proprietário e aos colaboradores. O Space não aparecerá nos resultados de busca e outros usuários receberão um erro 404 ao visitar sua URL.

Recursos de hardware

Cada ambiente de Spaces é limitado, por padrão, a 16GB de RAM, 2 núcleos de CPU e 50GB de espaço em disco (não persistente). O hardware padrão CPU Basic não tem custo por hora, mas a criação de um Space que roda em compute (Gradio ou Docker) requer um plano pago, enquanto os Spaces Estáticos são gratuitos para todos. Você pode fazer upgrade para um hardware melhor, incluindo uma variedade de aceleradores de GPU, por um preço competitivo. Para solicitar um upgrade, clique no botão Settings no seu Space e selecione o ambiente de hardware de sua preferência.

Nota: Encontre informações de preços mais detalhadas e completas em nossa página de preços.

Você tem um Space incrível, mas precisa de ajuda para cobrir os custos de upgrade de hardware? Adoramos apoiar quem tem um Space inovador, então sinta-se à vontade para se candidatar a uma doação de GPU da comunidade usando o link na aba Settings do seu Space e veja se o seu é selecionado!

Leia mais em nossas seções dedicadas a Spaces GPU Upgrades e Spaces Disk Usage & Storage.

Gerenciando segredos e variáveis de ambiente

Se o seu aplicativo requer variáveis de ambiente (por exemplo, chaves secretas ou tokens), não as codifique diretamente no seu aplicativo! Em vez disso, vá para a página de Configurações do repositório do seu Space e adicione uma nova variável ou segredo. Use variáveis se precisar armazenar valores de configuração não sensíveis e segredos para armazenar tokens de acesso, chaves de API ou qualquer valor sensível ou credencial.

Você pode usar:

• Variáveis caso você precise armazenar valores de configuração não confidenciais. Elas são acessíveis e visíveis publicamente e serão adicionadas automaticamente aos Spaces duplicados a partir dos seus.
• Segredos para armazenar tokens de acesso, chaves de API ou qualquer valor ou credencial sensível. Eles são privados e seu valor não pode ser lido na página de configurações do Space após serem definidos. Eles não serão adicionados a Spaces duplicados a partir do seu repositório.

O acesso a segredos e variáveis é diferente dependendo do seu Space SDK:

• Para os Espaços Estáticos, ambos estão disponíveis por meio de JavaScript no lado do cliente em window.huggingface.variables
• Para os Docker Spaces, confira gerenciamento de ambiente com Docker

Para outros Spaces, ambos são expostos ao seu aplicativo como variáveis de ambiente. Aqui está um exemplo muito simples de acessar a variável MODEL_REPO_ID declarada anteriormente em Python (seria o mesmo para segredos):

import os
print(os.getenv('MODEL_REPO_ID'))

Os proprietários de Spaces são alertados quando nosso Spaces Secrets Scanner encontra segredos codificados.

Duplicando um Space

Duplicar um Space pode ser útil se você quiser criar uma nova demonstração usando outra demonstração como modelo inicial. Spaces duplicados também podem ser úteis se você quiser ter um Space Upgraded individual para seu uso com inferência rápida.

Se você deseja duplicar um Space, clique nos três pontos no canto superior direito do space e clique em Duplicate this Space. Ao fazer isso, você poderá alterar os seguintes atributos:

• Proprietário: O Space duplicado pode estar na sua conta ou em qualquer organização na qual você tenha acesso de escrita
• Nome do espaço
• Visibilidade: O Space é privado por padrão. Leia mais sobre as opções de visibilidade aqui.
• Hardware: Você pode escolher o hardware no qual o Space será executado. Leia mais sobre upgrades de hardware aqui.
• Armazenamento: se o repositório original usa um bucket de armazenamento, você será solicitado a configurar o armazenamento. Leia mais sobre o uso de disco e armazenamento aqui.
• Segredos e variáveis: se o repositório original tiver definido alguns segredos e variáveis, você poderá defini-los ao duplicar o repositório.

Alguns Spaces podem ter variáveis de ambiente que você precisará configurar. Nesses casos, o fluxo de duplicação preencherá automaticamente as Variáveis públicas do Space de origem e exibirá um aviso sobre a configuração dos Secrets. O Space duplicado usará o hardware CPU Basic por padrão, mas você pode fazer um upgrade posteriormente, se necessário. A duplicação segue as mesmas regras da criação de um novo Space: duplicar um Space Gradio ou Docker exige um plano pago para a conta ou organização de destino (com a mesma exceção do ZeroGPU free tier para contas pessoais).

Networking

Se o seu Space precisar fazer solicitações de rede, você pode fazer solicitações através das portas padrão HTTP e HTTPS (80 e 443), além da porta 8080. Qualquer solicitação destinada a outras portas será bloqueada.

Gestão de ciclo de vida

Em hardware gratuito, seu Space entrará em “modo de espera” e deixará de executar após um período de inatividade. Se você deseja que seu Space execute indefinidamente, considere fazer upgrade para hardware pago. Você também pode pausar manualmente seu Space na aba Settings. Um Space pausado deixa de executar até que alguém com acesso de escrita o reinicie. O tempo em pausa não é cobrado.

Variáveis de ambiente integradas

Em alguns casos, você pode ter interesse em ter acesso programático ao autor do Space ou ao nome do repositório. Essa funcionalidade é particularmente útil quando você espera que os usuários dupliquem seu Space. Para ajudar com isso, os Spaces expõem diferentes variáveis de ambiente em tempo de execução (veja também variáveis de ambiente integradas em Jobs). Dado um Space osanseviero/i-like-flan:

• ACCELERATOR: O tipo de acelerador disponível (por exemplo, t4-medium, a10g-small), ou none para Spaces apenas com CPU.
• CPU_CORES: 4
• MEMORY: 15Gi
• SPACE_AUTHOR_NAME: osanseviero
• SPACE_REPO_NAME: i-like-flan
• SPACE_TITLE: I Like Flan (especificado no arquivo README)
• SPACE_ID: osanseviero/i-like-flan
• SPACE_HOST: osanseviero-i-like-flan.hf.space
• SPACE_CREATOR_USER_ID: 6032802e1f993496bc14d9e3 - Este é o ID do usuário que originalmente criou o Space. É útil quando o Space pertence a uma organização. Você pode obter as informações do usuário com uma chamada de API para https://huggingface.co/api/users/{SPACE_CREATOR_USER_ID}/overview.
• SPACE_SIGNING_SECRET: um segredo aleatório e exclusivo do seu Space, exposto como um segredo. Ele permanece o mesmo entre reinicializações, reconstruções e réplicas, permitindo que você o use para assinar itens como cookies, estado de OAuth ou tokens CSRF. Para usar seu próprio valor, adicione um segredo chamado SPACE_SIGNING_SECRET nas configurações do seu Space.

Caso o OAuth esteja habilitado para o seu Space, as seguintes variáveis também estarão disponíveis:

• OAUTH_CLIENT_ID: o ID do cliente do seu aplicativo OAuth (público)
• OAUTH_CLIENT_SECRET: o segredo do cliente do seu aplicativo OAuth
• OAUTH_SCOPES: escopos acessíveis pelo seu aplicativo OAuth. Atualmente, isso é sempre "openid profile".
• OPENID_PROVIDER_URL: A URL do provedor OpenID. Os metadados do OpenID estarão disponíveis em {OPENID_PROVIDER_URL}/.well-known/openid-configuration.

Clone o Repositório

Você pode clonar facilmente o repositório do seu Space localmente. Comece clicando no menu suspenso no canto superior direito da página do seu Space:

Selecione “Clone repository” e, em seguida, você poderá seguir as instruções para clonar o repositório do Space para sua máquina local usando HTTPS ou SSH.

Vinculando modelos e conjuntos de dados no Hub

Você pode exibir todos os modelos e conjuntos de dados que seu Space vincula adicionando seus identificadores nos metadados do README do seu Space. Para isso, você pode defini-los sob as chaves models e datasets. Além de listar os artefatos no arquivo README, você também pode registrá-los em qualquer arquivo .py, .ini ou .html. Nós faremos a análise automaticamente!

Aqui está um exemplo que vincula dois modelos de um espaço:

title: My lovely space
emoji: 🤗
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
models:
- reach-vb/musicgen-large-fp16-endpoint
- reach-vb/wav2vec2-large-xls-r-1B-common_voice7-lt-ft