Docs · API nativa
Embeddings
Transforma texto em vetores.
POST/api/v1/embeddings#
- Auth: a sua chave de API. Uma chave cujo grupo de conta não tem acesso à API é recusada com
401. - Limite: 30 requisições por minuto por conta por padrão, no contador que os outros endpoints limitados dividem. Veja limites e cotas.
- Corpo: JSON, com
Content-Type: application/json.
curl -s "$SHVIA_URL/api/v1/embeddings" \
-H "Authorization: Bearer $SHVIA_API_KEY" -H "Content-Type: application/json" \
-d '{ "input": ["How do I restart the service?", "Where are the logs?"] }'{
"embeddings": [
[0.0123, -0.0456, 0.0789],
[0.0101, -0.0222, 0.0333]
],
"model": "nomic-embed-text",
"server": "…",
"server_label": "…",
"dimensions": 768
}Os vetores acima estão encurtados: um vetor de verdade tem dimensions números. server e server_label dizem qual servidor gerou os embeddings do texto. Os valores deles pertencem à instalação.
Requisição#
| Campo | Notas |
|---|---|
input | obrigatório. Uma string, ou um array de strings. Cada item tem de ser uma string não vazia. No máximo 64 itens, e 8000 caracteres por item, por padrão |
server | string opcional, até 64 caracteres: a chave de um dos servidores do próprio operador, que é o que gera os embeddings. Provedores de nuvem são recusados. Deixe de fora para usar o servidor padrão da instalação, e pergunte ao operador se precisar escolher outro |
Você não escolhe o modelo de embeddings: cada servidor tem o que o operador configurou para ele. Escolher um servidor, portanto, escolhe o modelo e o tamanho dos vetores, então leia dimensions e model na resposta e não misture vetores de modelos diferentes num mesmo índice.
Resposta#
embeddings é sempre um array de vetores, mesmo para uma só entrada, na ordem dos itens enviados. Não há contagem de tokens, e a chamada não conta na sua cota de tokens.
Erros#
| Status | Corpo | Quando |
|---|---|---|
| 401 | {"message": "Unauthenticated."} | a credencial não é válida |
| 400 | {"detail": "…"} | o server é desconhecido ou está desativado |
| 403 | {"detail": "…"} | um token de sessão cujo grupo de conta não tem acesso à API. Uma chave nessa situação recebe 401 |
| 422 | {"message", "errors": {…}} | input está ausente ou vazio |
| 422 | {"detail": "…"} | um item está vazio, há itens demais, ou um item é longo demais |
| 429 | {"message": "Too Many Attempts."} | limite de requisições atingido |
| 502 | {"detail": "…"} | o servidor de embeddings não pôde ser alcançado ou falhou |
| 503 | {"detail": "…"} | o servidor de embeddings está offline |
Repare que o 422 tem dois formatos neste endpoint: decida pelo status, depois leia errors se ele estiver presente e detail se não estiver.