Gerenciar repositórios

mka1-repos é o serviço de repositórios da plataforma para pesos de modelos e conjuntos de dados. Todo repositório é um repositório git comum com Git LFS, pertencente a exatamente uma organização e identificado pelo par <org>/<name> — por exemplo, meetkai/functionary. Esse identificador é o ponto principal. Você envia artefatos ao repositório da sua máquina via git, e as cargas de trabalho do Compute resolvem o mesmo <org>/<name> por meio do endpoint de artefatos compatível com Hugging Face da plataforma para treiná-los ou servi-los. Este guia aborda ambas as partes: a API de gerenciamento para criar, listar, renomear e excluir repositórios, e as duas ferramentas de cliente — git e a CLI do Hugging Face — que movem dados para dentro e para fora.

Antes de começar

Você precisa de:

Requisito	Observações
Chave de API	Envie-a como `Authorization: Bearer <mka1-api-key>` em cada solicitação.
Função de proprietário ou administrador da organização	Todo endpoint de repositório é restrito a proprietários e administradores da organização. Não há permissões por repositório; o acesso é decidido apenas pela sua função na organização.
`git` e `git-lfs`	Os pesos de modelos são binários grandes; o host git os armazena por meio do Git LFS, portanto instale e inicialize `git lfs` antes do primeiro envio.

Os repositórios sempre pertencem à organização do chamador. Você nunca escolhe a org no momento da criação — ela é derivada da sua chave de API — e você não pode acessar os repositórios de outra organização.

Criar um repositório

Escolha um nome e, opcionalmente, uma descrição. O nome deve começar com uma letra ou dígito e ter no máximo 100 caracteres entre letras, dígitos, pontos, sublinhados e hífens (^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$).

import { SDK } from '@meetkai/mka1';

const sdk = new SDK({
  bearerAuth: 'Bearer <mka1-api-key>',
});

const repo = await sdk.repos.create({
  createRepoRequest: {
    name: 'functionary',
    description: 'Pesos ajustados para o assistente MeetKai.',
  },
});
console.log(repo.org, repo.name, repo.id);

curl https://apigw.mka1.com/api/v1/repos \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{
    "name": "functionary",
    "description": "Pesos ajustados para o assistente MeetKai."
  }'

A resposta é 201 com o repositório:

{
  "id": "rqz4h6k2m5n7p9r3t5v7w9x2",
  "org": "meetkai",
  "name": "functionary",
  "description": "Pesos ajustados para o assistente MeetKai.",
  "created_at": "2026-07-30T09:15:00Z"
}

id é um identificador opaco e estável — a chave canônica que sobrevive a renomeações. org e name são os rótulos voltados ao usuário que formam a referência do repositório e suas URLs. A criação provisiona o repositório git de suporte como parte da solicitação. Se esse provisionamento falhar, a criação retorna 502 provision_failed e nada é mantido, portanto é seguro tentar novamente. O corpo da solicitação rejeita campos desconhecidos, e um nome que já esteja em uso na sua organização retorna 409.

A referência do repositório e a URL git

Dois valores identificam um repositório em todos os demais locais da plataforma:

Valor	Formato	Usado para
Referência do repositório	`<org>/<name>`, por exemplo, `meetkai/functionary`	Resolução compatível com Hugging Face dentro de cargas de trabalho do Compute e ferramentas como ms-swift e vLLM.
URL git	`https://git.mka1.com/<org>/<name>.git`	`git clone`, `git push` e transferências do Git LFS das suas próprias máquinas.

O host git autentica com autenticação básica HTTP: o nome de usuário deve ser o slug da sua organização e a senha é uma chave de API MKA1. org:apikey é imposto — um nome de usuário que não corresponde à organização é rejeitado. Ambos os valores são aqueles que você fornece a uma carga de trabalho do Compute como variáveis de ambiente — consulte Executar um trabalho de ajuste fino e Implantar um servidor de modelos.

Listar repositórios

Retorna todos os repositórios da sua organização.

const { repos } = await sdk.repos.list({});
for (const repo of repos) {
  console.log(`${repo.org}/${repo.name}`, repo.description);
}

curl https://apigw.mka1.com/api/v1/repos \
  --header 'Authorization: Bearer <mka1-api-key>'

{
  "repos": [
    {
      "id": "rqz4h6k2m5n7p9r3t5v7w9x2",
      "org": "meetkai",
      "name": "functionary",
      "description": "Pesos ajustados para o assistente MeetKai.",
      "created_at": "2026-07-30T09:15:00Z"
    },
    {
      "id": "rb8s2d4f6h8j1l3n5q7s9v2x",
      "org": "meetkai",
      "name": "support-conversations",
      "description": "Transcrições de suporte selecionadas para ajuste fino.",
      "created_at": "2026-07-28T16:40:00Z"
    }
  ]
}

Obter um repositório

Leia um único repositório pela sua referência.

const repo = await sdk.repos.get({
  org: 'meetkai',
  name: 'functionary',
});
console.log(repo.description);

curl https://apigw.mka1.com/api/v1/repos/meetkai/functionary \
  --header 'Authorization: Bearer <mka1-api-key>'

Um repositório que não existe na sua organização retorna 404 — incluindo qualquer repositório que pertença a uma organização diferente.

Renomear ou atualizar um repositório

As atualizações afetam apenas rótulos: você pode alterar name e description, e um campo omitido permanece inalterado.

const repo = await sdk.repos.update({
  org: 'meetkai',
  name: 'functionary',
  patchRepoRequest: {
    name: 'functionary-v2',
  },
});
console.log(repo.name);

curl https://apigw.mka1.com/api/v1/repos/meetkai/functionary \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --data '{"name": "functionary-v2"}'

O id do repositório é estável, portanto uma renomeação é uma atualização de metadados — o histórico git e os artefatos armazenados permanecem intactos. Renomear para um nome que já existe na sua organização retorna 409.

Uma renomeação altera a referência do repositório e a URL git.O antigo <org>/<name> deixa de ser resolvido imediatamente. Atualize cada remoto git, cada valor de ambiente REPO/REPO_URL nos corpos de criação do Compute e cada script de treinamento ou serviço que referenciava o nome antigo.

Excluir um repositório

await sdk.repos.delete({
  org: 'meetkai',
  name: 'functionary',
});

curl https://apigw.mka1.com/api/v1/repos/meetkai/functionary \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>'

A resposta é 204 sem corpo. O registro do repositório é removido imediatamente — essa exclusão é autoritativa — enquanto a desmontagem do armazenamento git de suporte é uma limpeza de melhor esforço. Uma exclusão repetida da mesma referência retorna 404.

Excluir um repositório remove o repositório, seu histórico git e todos os artefatos armazenados. Isso não pode ser desfeito — não há exclusão reversível nem janela de recuperação.

Enviar e obter com git

Clone o repositório ou adicione-o como remoto de um repositório local existente:

git clone https://git.mka1.com/meetkai/functionary-train-data.git
cd support-conversations

# Em vez disso, em um repositório local existente:
git remote add mka1 https://git.mka1.com/meetkai/functionary-train-data.git

Rastreie binários grandes com Git LFS antes de confirmá-los. Os arquivos de pesos devem passar pelo LFS; arquivos de texto pequenos, como configurações, definições de tokenizador e conjuntos de dados JSONL, podem permanecer no git comum.

git lfs install
git lfs track "*.safetensors" "*.bin" "*.gguf"
git add .gitattributes

Em seguida, confirme e envie normalmente:

git add .
git commit -m "Adicionar transcrições de suporte selecionadas"
git push origin main   # or: git push mka1 main

O Git autentica o envio com autenticação básica HTTP. O nome de usuário deve ser o slug da sua organização e a senha é uma chave de API MKA1 — org:apikey é imposto, portanto um nome de usuário que não corresponde à organização é rejeitado:

Username for 'https://git.mka1.com': meetkai
Password for 'https://meetkai@git.mka1.com': <mka1-api-key>

Para envios não interativos (CI, uma máquina de treinamento), exporte a chave de API como MK_API_KEY no ambiente (por exemplo, a partir de um segredo de CI) e forneça-a por meio de um auxiliar de credenciais git, em vez de incorporar a chave na URL remota, onde ela seria gravada em .git/config:

git config credential.helper '!f() { echo "username=meetkai"; echo "password=$MK_API_KEY"; }; f'

Organize o repositório da forma esperada pela sua pilha de treinamento ou serviço. Os exemplos deste guia usam dois repositórios: meetkai/functionary-train-data, um repositório de conjuntos de dados que contém transcrições JSONL, e meetkai/functionary, um repositório de pesos no layout usual do Hugging Face (config.json, arquivos do tokenizador, *.safetensors).

Enviar e obter com a CLI do Hugging Face

O mesmo repositório pode ser acessado pela API do Hugging Face Hub. Defina o endpoint e o token e desabilite o Xet para que os envios usem o caminho padrão Hub/LFS compatível com o mka1-repos:

export HF_ENDPOINT=https://hf.mka1.com
export HF_TOKEN=<mka1-api-key>
export HF_HUB_DISABLE_XET=1

Com elas definidas, os comandos comuns do Hugging Face operam nos seus repositórios em vez do hub público:

hf download meetkai/functionary --local-dir ./base
hf download meetkai/functionary-train-data --repo-type dataset --local-dir ./data
hf upload meetkai/functionary ./merged .

As mesmas variáveis funcionam no Python, pois huggingface_hub as lê pelo nome:

from huggingface_hub import snapshot_download

path = snapshot_download(repo_id="meetkai/functionary")

hf é a CLI atual; ambientes mais antigos fornecem os mesmos comandos como huggingface-cli. Diferentemente do git, este caminho não exige o slug da sua organização como nome de usuário — o token carrega a identidade.

Esta é a parte que é transferida para o Compute. Um contêiner de treinamento ou serviço define as mesmas duas variáveis, e ms-swift ou vLLM resolve <org>/<name> sem alterações de código — consulte Executar um trabalho de ajuste fino e Implantar um servidor de modelos.

Erros

Os endpoints de repositório retornam um envelope uniforme com um código estável legível por máquina e o ID de correlação da solicitação:

{
  "error": "not_found",
  "correlation_id": "c0a8f3d2-4b6e-4f1a-9c7d-2e5b8a1f6d3c"
}

Status	Código	Significado
`400`	`invalid_name`, `invalid_body`	Um nome que viola o padrão, ou um corpo malformado ou campo desconhecido (os corpos rejeitam propriedades desconhecidas).
`401`	`unauthorized`	Identidade no escopo da organização ausente ou incompleta na solicitação.
`403`	`forbidden`	O chamador não é proprietário nem administrador da organização.
`404`	`not_found`	Não existe tal repositório na sua organização — um repositório em outra organização é informado como `404`, nunca `403`, portanto sua existência nunca é exposta.
`409`	`name_taken`	O nome já está em uso na sua organização (criação ou renomeação).
`500`	`internal`	Um erro inesperado no lado do servidor.
`502`	`provision_failed`	Não foi possível criar o repositório git de suporte; o repositório não foi mantido, portanto tente a criação novamente.
`503`	`org_unresolved`	O gateway não conseguiu resolver sua organização; tente novamente e entre em contato com o suporte se o problema persistir.

Referência da API

Para os esquemas completos de solicitação e resposta, abra os grupos Repositories na Referência da API.

Veja também

Executar um trabalho de ajuste fino - publique pesos mesclados em um repositório a partir de um trabalho de treinamento.
Implantar um servidor de modelos - sirva pesos diretamente de um repositório com vLLM.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Gerenciar repositórios

Antes de começar

Criar um repositório

A referência do repositório e a URL git

Listar repositórios

Obter um repositório

Renomear ou atualizar um repositório

Excluir um repositório

Enviar e obter com git

Enviar e obter com a CLI do Hugging Face

Erros

Referência da API

Veja também

​Antes de começar

​Criar um repositório

​A referência do repositório e a URL git

​Listar repositórios

​Obter um repositório

​Renomear ou atualizar um repositório

​Excluir um repositório

​Enviar e obter com git

​Enviar e obter com a CLI do Hugging Face

​Erros

​Referência da API

​Veja também

Antes de começar

Criar um repositório

A referência do repositório e a URL git

Listar repositórios

Obter um repositório

Renomear ou atualizar um repositório

Excluir um repositório

Enviar e obter com git

Enviar e obter com a CLI do Hugging Face

Erros

Referência da API

Veja também