Produit Démo Docs Blogue À propos Contact Se connecter S'inscrire

Documentation

Soumettez des tâches d'inférence vérifiée en un seul appel Python. Recevez en retour des embeddings numpy et un reçu inviolable qui prouve l'exactitude du résultat. Propulsé par le paquet cyberian-client.

Aperçu

Vous nommez un modèle, vous envoyez vos entrées, vous récupérez vos sorties accompagnées d'un reçu inviolable. La plateforme s'occupe de l'exécution, de la vérification indépendante, et des attestations cryptographiques qui rendent le résultat auditable.

  • API synchrone : un seul appel soumet et attend.
  • Exceptions typées : distingue auth, quota, limite de débit, échecs de vérification.
  • Sorties numpy : les embeddings reviennent sous forme de np.ndarray(shape=(N, D), dtype=float32).

Installation

Python 3.9+ requis.

pip install cyberian-client

Voir sur PyPI : pypi.org/project/cyberian-client et consultez l'historique des versions, les empreintes des paquets, le fil de publications.

Authentification

Obtenez une clé via la page d'inscription. Passez-la au constructeur du client ou définissez la variable d'environnement CYBERIAN_API_KEY.

from cyberian import Client

client = Client(api_key="cyb_votretiquette_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
# ou : client = Client()  # lit CYBERIAN_API_KEY depuis l'environnement
Gardez vos clés secrètes. Ne les commettez jamais dans git. Utilisez des variables d'environnement, un gestionnaire de secrets ou le coffre de votre fournisseur CI.

Soumettre votre première tâche

L'appel le plus simple est submit_and_wait - il soumet, interroge jusqu'au règlement, puis récupère le reçu et le tableau de sortie.

from cyberian import Client

client = Client()

texts = [
    "Le vif renard brun saute par-dessus le chien paresseux.",
    "Cyberian Systems vérifie l'inférence IA de bout en bout.",
    "Les reçus Merkle rendent les sorties auditables.",
]

result = client.submit_and_wait(
    model="bge-large-v1.5",
    inputs=texts,
)

print("Tâche :", result.job["id"])
print("Reçu :", result.receipt["receipt_id"])
print("Forme :", result.embeddings.shape)  # (3, 1024)
print("Type :", result.embeddings.dtype)  # float32

Étape par étape (miroir de l'enchaînement REST)

Les mêmes cinq appels que parcourt le Flux typique REST, exprimés en méthodes SDK. Utile lorsque vous voulez un contrôle explicite sur chaque étape (p. ex. inspecter la tâche avant règlement, isoler la passe de vérification pour un journal d'audit).

# 1. soumettre une tâche
job = client.submit_job(model="bge-large-v1.5", inputs=texts)
print(job["id"], job["status"])  # EXECUTING

# 2. bloquer jusqu'à un état terminal (SETTLED / FAILED / REFUNDED)
settled = client.wait_for_completion(job["id"], timeout_sec=600)

# 3. récupérer le reçu Merkle allégé
receipt = client.get_receipt(settled["receipt_id"])

# 4. passe de vérification côté serveur — recalcule chaque hachage
check = client.verify_receipt(settled["receipt_id"])
assert check["valid"], check["errors"]

# 5. récupérer les embeddings (remise en forme via les en-têtes pour vous)
embeddings = client.get_job_output(settled["id"])  # np.ndarray(N, D)

Modèles

Chaque tâche nomme un model (model="..."). Pour lister les modèles activés pour votre compte :

info = client.list_models()
print(info["models"])

La plateforme est agnostique au modèle. Vous avez besoin d'un modèle qui n'est pas activé pour vous ? Écrivez à support@cyberiansystems.ai avec la référence du modèle (par ex. une URL Hugging Face). L'intégration d'un nouveau modèle est une étape de configuration de notre côté - aucun changement de code chez vous.

Vérifier un reçu

Chaque tâche réglée produit un reçu inviolable qui ancre les entrées, les sorties et l'attestation de vérification dans des racines Merkle cryptographiques. Vous pouvez le valider hors ligne :

receipt = client.get_receipt(result.receipt["receipt_id"])
verified = client.verify_receipt(receipt["receipt_id"])
assert verified["valid"] is True
print(verified["checks"])

Si un seul octet du reçu est modifié, le vérificateur retourne valid=False avec des détails sur la cause - c'est la piste d'audit sur laquelle vos clients (ou les régulateurs) peuvent s'appuyer.

Champs du reçu

ChampDescription
receipt_idIdentifiant unique du reçu.
job_idTâche que ce reçu atteste.
spec_hashHachage opaque de la spécification d'exécution utilisée.
inputs_rootRacine Merkle de vos entrées.
outputs_rootRacine Merkle des sorties produites.
verification_attestationRacine Merkle engageant le travail de vérification indépendante.
executor_attestation_idsIdentifiants opaques des fournisseurs de calcul impliqués.
issued_atHorodatage ISO-8601 de l'émission.
receipt_hashSHA-256 auto-référentiel - ce que verify_receipt recalcule.

Vérification en tant que service

Si vous exécutez l'inférence sur votre propre infrastructure et avez besoin d'une attestation indépendante, utilisez le point de terminaison VaaS. Vous soumettez vos entrées et le SHA-256 de vos sorties calculées ; la plateforme vérifie indépendamment et émet un reçu.

import hashlib

mes_outputs_hash = hashlib.sha256(mes_embeddings.tobytes()).hexdigest()

receipt = client.verify_outputs(
    model="bge-large-v1.5",
    inputs=texts,
    claimed_output_commitment=mes_outputs_hash,
)

Compte

client.get_account() retourne un dictionnaire décrivant votre compte, l'utilisation courante et les clés associées :

ChampDescription
account_idUUID de votre compte.
nameNom affiché.
emailCourriel du compte.
usernameNom d'utilisateur du compte.
email_verified_atHorodatage ISO-8601, ou null si non vérifié.
tierPalier assigné (par ex. "free").
effective_tierPalier réellement facturé (change lorsque l'essai expire).
subscription_status"trial" | "active" | "none".
trial_started_atHorodatage ISO-8601.
trial_ends_atHorodatage ISO-8601.
chunks_consumed_periodChunks consommés dans la période courante.
chunks_period_started_atHorodatage ISO-8601 du début de période.
limitsObjet avec les plafonds du palier effectif - voir ci-dessous.
keysTableau de descripteurs de clé - voir ci-dessous.

limits

ChampDescription
chunks_per_periodPlafond de chunks par période.
period_length_daysLongueur de la période, en jours.
chunks_per_dayPlafond quotidien.
chunks_per_minutePlafond soutenu par minute.
max_chunks_per_requestPlafond de chunks par requête.
max_inputsNombre maximum d'entrées par requête.

keys[i]

ChampDescription
key_idPréfixe de 12 caractères - à passer à revoke_key.
labelÉtiquette donnée à la clé lors de sa création.
created_atHorodatage ISO-8601.
last_used_atHorodatage ISO-8601, ou null si jamais utilisée.
revoked_atHorodatage ISO-8601, ou null si active.

Tous les horodatages sont des chaînes ISO-8601 en UTC.

Erreurs et reprises

Le client lève des exceptions typées que vous pouvez attraper de façon granulaire :

ExceptionCauseAction recommandée
AuthErrorClé API invalide ou révoquéeRéémettre la clé sur la page de compte
TrialExpiredErrorPériode d'essai écouléeNous écrire pour mise à niveau ou prolongation
QuotaErrorQuota périodique ou quotidien atteintAttendre la réinitialisation, ou en demander plus
RateLimitErrorDébit par minute dépasséReculer ; le SDK expose retry_after
ServiceBusyErrorProfondeur de file ou capacité atteinteRéessayer avec backoff
JobFailedErrorUn ou plusieurs chunks ont échoué à la vérificationInspecter err.failed_chunks
VerificationFailedErrorLe reçu n'a pas validé hors ligneTraiter la sortie comme non fiable
NetworkErrorErreur de transport (aucune réponse HTTP reçue)wait_for_completion réessaie automatiquement ; ailleurs, réessayer avec backoff
ApiErrorAutres 4xx/5xxInspecter err.status et err.body
from cyberian import Client, RateLimitError, QuotaError

client = Client()

try:
    result = client.submit_and_wait(model="bge-large-v1.5", inputs=texts)
except RateLimitError as e:
    time.sleep(e.retry_after)
except QuotaError:
    print("Chunks d'essai épuisés - écrivez-nous pour prolonger.")

Limites de l'essai

  • 14 jours à partir de la vérification du courriel (pas de l'inscription — le compteur démarre lorsque vous cliquez sur le lien de confirmation)
  • 400 chunks par période d'essai
  • 100 chunks par jour
  • 60 chunks par minute en régime soutenu
  • Maximum 100 chunks par requête, jusqu'à 1 000 textes d'entrée par requête

Les limites au-delà de l'essai sont fournies sur demande - écrivez à support@cyberiansystems.ai.

Référence du client

Constructeur

Client(api_key: str | None = None)

Si api_key est omis, le client lit CYBERIAN_API_KEY depuis l'environnement.

Méthodes

MéthodeRetourDescription
submit_job(model, inputs)dictSoumettre une tâche.
get_job(job_id)dictRécupérer l'état courant.
wait_for_completion(job_id, timeout_sec=600)dictAttend que la tâche atteigne SETTLED, FAILED, ou délai écoulé.
get_job_output(job_id)np.ndarrayTenseur de sortie, dtype float32.
get_receipt(receipt_id)dictLe reçu public - voir « Champs du reçu » ci-dessus.
verify_receipt(receipt_id)dictValider le reçu.
submit_and_wait(model, inputs)JobResultCommodité tout-en-un.
verify_outputs(model, inputs, claimed_output_commitment)dictVoie VaaS - reçu pour vos sorties.
list_models()dictModèles activés pour votre compte.
get_account()dictProfil, compteurs d'utilisation, liste de clés.

JobResult

@dataclass
class JobResult:
    job:           dict
    receipt:       dict
    embeddings:    np.ndarray
    verification:  dict | None

Support

Questions, rapports de bogues, demandes de mise à niveau : support@cyberiansystems.ai.