Pular para o conteúdo principal

Playground e Busca de embeddings

Um projeto de embeddings tem duas formas de experimentar um modelo base público ou um modelo de embeddings hospedado antes de construir sobre ele: o Playground, que gera embeddings e compara alguns textos, e a Busca, que classifica os trechos de um conjunto de dados contra uma consulta. Os dois chamam o mesmo modelo e são cobrados como chamadas a /embeddings.

Playground​

Em Modelos hospedados, escolha Usar modelo e depois Abrir no Playground para abrir o projeto com o modelo de embeddings selecionado. Abrir o Playground não envia uma requisição de inferência; use Comparar, Gerar embedding ou Busca para executar uma.

O seletor de modo sempre mostra Busca, Similaridade e Vetor. A Busca fica desabilitada com uma explicação quando a indexação não está disponível ou o projeto não tem um modelo de embeddings disponível. Modelos base funcionam nos três modos sem ajuste fino nem criação de alias hospedado. A Similaridade inclui exemplos de reembolso e acesso à API. Escolher um exemplo apenas preenche os campos; pressionar Comparar envia a requisição de inferência cobrada. Dimensões, normalização e instruções de consulta seguem o modelo servido, sem substituição por requisição. O rótulo Modelo base identifica um modelo do catálogo.

POST /api/v1/projects/{owner_slug}/{project_slug}/playground/embeddings/vector
POST /api/v1/projects/{owner_slug}/{project_slug}/playground/embeddings/similarity

Vector recebe {model, input, input_type} e retorna os vetores dos seus textos, com a revisão exata do modelo (target) que os produziu e a instrução efetiva. input_type é query ou document; um modelo treinado com query_instruction a aplica só às consultas.

Similarity recebe {model, source, documents} e retorna a similaridade de cosseno de cada documento com a consulta, na ordem de entrada. Ela gera o embedding da consulta e depois o dos documentos, em lotes, e cada um é cobrado como uma requisição de embeddings: usage.billable_requests diz quantas. Se uma requisição posterior falhar, as anteriores ainda podem ser cobradas. Vector é cobrado da mesma forma.

Valem os mesmos limites de entrada de /embeddings, e eles são aplicados no servidor.

Busca​

Use um ID público como ReOpenly/Qwen3-Embedding-0.6B ou um alias hospedado no mesmo campo model. Um índice base retorna saved_model_id: null, base_model_artifact_id e o ID público em model; um índice hospedado mantém saved_model_id inteiro. Ambos fixam o artefato e a política de inferência, com as mesmas permissões, cobrança, cotas e cancelamento. Alterações ou indisponibilidade do modelo base tornam o índice desatualizado.

Escolha o conjunto de dados pelo nome em Corpus. A Busca classifica os trechos da captura indexada contra uma consulta. Os IDs das capturas ficam em Detalhes da captura, fora do seletor principal.

GET    /api/v1/projects/{owner_slug}/{project_slug}/search/corpora
GET    /api/v1/projects/{owner_slug}/{project_slug}/search/versions
GET    /api/v1/projects/{owner_slug}/{project_slug}/search/indexes
POST   /api/v1/projects/{owner_slug}/{project_slug}/search/indexes
POST   /api/v1/projects/{owner_slug}/{project_slug}/search/indexes/{index_id}/query
POST   /api/v1/projects/{owner_slug}/{project_slug}/search/indexes/{index_id}/cancel
DELETE /api/v1/projects/{owner_slug}/{project_slug}/search/indexes/{index_id}

Criar um índice. GET /search/corpora lista os conjuntos de dados de embeddings ativos pelo nome, com contagens de exemplos e digests da seleção atual. Envie dataset_id, model e credit_ceiling a POST /search/indexes. Isso captura o conjunto de dados atual completo, sem treinamento ou divisão entre treino e avaliação. A API também aceita dataset_version_id para uma captura existente; envie exatamente um desses identificadores. GET /search/versions mostra as capturas históricas e os limites da Busca. Criar um índice gera os embeddings de cada trecho positivo e negativo distinto com o modelo base público ou hospedado que você escolher, em lotes cobrados no preço normal desse modelo; cada lote aparece no seu registro de créditos. Você define um teto de créditos para a criação: ela para de enviar lotes quando o gasto chega ao teto, e um lote já em andamento pode terminar um pouco acima dele. Um índice está pronto quando o status indica; embedded_count e spent_credits mostram o progresso.

Alterações no conjunto de dados. As alterações não modificam o índice existente nem iniciam uma reconstrução cobrada automaticamente. O Playground mostra Conjunto de dados alterado quando o digest atual difere da captura indexada. Escolha Atualizar índice e aprove um limite de créditos para capturar e indexar o conteúdo novo. O índice antigo permanece disponível até ser excluído e continua contando na cota de armazenamento.

Apenas um índice pode ser criado por vez em um projeto, inclusive uma criação em fila aguardando um endpoint. Trocar o modelo ou o Corpus não libera essa vaga. O Playground identifica uma criação bloqueadora fora da seleção atual e oferece Parar indexação; Criar e Atualizar ficam desativados até ela parar ou terminar. Também é possível parar um índice em fila ou execução no inventário em detalhes da captura, carregando índices antigos quando necessário. Índices prontos continuam disponíveis para busca.

Parar a indexação. Criações em fila, em execução ou aguardando nova tentativa oferecem Parar indexação, também disponível em POST /search/indexes/{index_id}/cancel. A ação interrompe o índice e impede novas tentativas automáticas. Um lote já iniciado pode terminar o processamento, mas sua resposta tardia não pode gravar vetores ou uma cobrança após o cancelamento. Cobranças já confirmadas e progresso parcial permanecem visíveis. Parar não libera armazenamento: exclua o índice interrompido quando não precisar mais dele. Repetir a ação é seguro; índices prontos ou com falha respondem 409 search_index_not_building, pois não há mais uma criação a interromper.

Consultar. Cada consulta gera o embedding do seu texto uma vez (uma requisição normal cobrada) e classifica o índice exatamente por similaridade de cosseno, retornando cada trecho com posição, pontuação, o exemplo de origem e se foi cortado.

Limites. Um índice guarda no máximo 20.000 trechos, e os índices de um projeto dividem 256 MB de armazenamento de vetores. Os vetores armazenados não têm cobrança à parte.

Índices desatualizados. Se o modelo hospedado for apontado para outro modelo, desativado ou alterado, ou se a versão não estiver mais disponível, o índice é marcado como desatualizado e recusa consultas: exclua-o e crie um novo. Excluir um índice remove seus trechos e vetores na hora; créditos já gastos não são devolvidos. Um índice que falhou continua contando na cota de armazenamento até ser excluído.

Se a Busca ou o Playground não estiverem disponíveis para o seu projeto, a API responde 409 project_capability_mismatch.

Cada campo dessas requisições e respostas está na referência da API.

Paginação do histórico​

GET /api/v1/playground/sessions sempre retorna {data, next_cursor, total_count}. Use limit (25 por padrão, máximo 100) e passe cursor=<next_cursor> para a próxima página. A lista omite mensagens e aceita o filtro de dono/projeto.

Solicitações salvas​

O Playground global permite alternar entre Texto e Embeddings e selecionar um projeto de embeddings no painel Parâmetros. O tipo e o projeto ficam na URL. Os três modos usam os modelos e o escopo de cobrança desse projeto.

Solicitações bem-sucedidas de Search, Similaridade e Vetor salvam entradas, modelo, configurações e resultados no Histórico, inclusive após sair da página ou recarregar. Abrir uma solicitação restaura o resultado sem executar ou cobrar outra inferência. Resultados de Search continuam sendo um retrato da solicitação original, mesmo se o corpus ou índice mudar.

O botão de excluir ao lado de cada entrada remove suas entradas e resultados salvos. Não exclui índice, dataset ou modelo e não reembolsa a inferência. O histórico é privado à conta e ao projeto, permanece até sua exclusão ou a exclusão da conta, e pode ser consultado ou excluído mesmo sem disponibilidade de inferência. Se o salvamento falhar, Tentar novamente salva o resultado sem repetir a inferência.

A API compartilhada aceita embedding_run tipado com mode, model, entradas do modo e result, limitado a 2 MB. São registros enviados pelo cliente, não provas independentes de cobrança ou qualidade. A listagem expõe embedding_mode sem entradas nem resultados; consulte uma sessão para lê-los. Use task=embedding ou task=text_generation para separar históricos; sem task, ambos são listados. O cursor pertence ao tipo e escopo originais.