Hy3 API-Schnellstart für agentische und kontextreiche Workflows

Tencent’s Hy3 ist auf Novita AI verfügbar mit der Modell-ID tencent/hy3, einem OpenAI-kompatiblen chat/completions-Endpunkt, einem 256K-Kontextfenster sowie Unterstützung für Funktionsaufrufe, strukturierte Ausgaben und drei Reasoning-Modi. Dieser Schnellstart behandelt die Entwicklereinrichtung: Konfigurieren Sie Ihren Client, senden Sie Ihre erste Anfrage, nutzen Sie Funktionsaufrufe, aktivieren Sie Reasoning und verstehen Sie die Ratenbegrenzungen, bevor Sie mit der Entwicklung beginnen.

Wann dieser Schnellstart verwendet werden sollte

Verwenden Sie diesen Leitfaden, wenn Sie eine funktionierende Anfrage an Hy3 benötigen, bevor Sie zusätzlichen Code schreiben. Er deckt einen praktischen Pfad ab: Wählen Sie die Modell-ID, authentifizieren Sie sich, senden Sie eine Testanfrage und erweitern Sie dann auf Funktionsaufrufe oder Reasoning, je nach Ihrem Workload-Bedarf.

Die Architektur von Hy3 – 295B gesamt, 21B aktiv als MoE – ist darauf ausgelegt, Qualität und Effizienz im großen Maßstab zu balancieren. Es ist eine Überlegung wert, wenn Sie folgende Anforderungen haben:

• Langkontext-Dokumentenverarbeitung (das 256K-Fenster fasst etwa 200.000 Wörter in einem Aufruf).
• Mehrrunden-Dialoge, die von einem großen aktiven Parameterbudget profitieren.
• Agentische Aufgaben, bei denen Tool-Aufrufe und zuverlässige Argumentformatierung wichtig sind.
• Code-Unterstützung, die große Codebasen ohne Aufteilung umfasst.

Dieser Leitfaden behandelt nur den API-Integrationspfad über Novita AI. Er deckt kein Self-Hosting, Fine-Tuning oder die Portierung auf andere Inferenz-Backends ab.

Schritt 1: Holen Sie sich Ihren Novita-API-Schlüssel

Erstellen Sie ein Novita AI-Konto und navigieren Sie zum Bereich „API-Schlüssel“ in Ihrer Konsole. Generieren Sie einen Schlüssel und speichern Sie ihn in einer Umgebungsvariable. Halten Sie ihn aus clientseitigem Code, Frontend-Bundles und öffentlichen Repositories fern.

export NOVITA_API_KEY="your_api_key"

Wenn Sie bereits das OpenAI Python SDK oder OpenAI-kompatible Clients in anderen Projekten verwenden, ist die Einrichtung hier dieselbe – ändern Sie die Basis-URL und den Modellnamen, sonst nichts.

Schritt 2: Bestätigen Sie Modell-ID und Endpunkt

Diese drei Werte sind alles, was Sie für die Konfiguration benötigen:

Element	Wert
API-Schlüssel	Ihr Novita AI API-Schlüssel, gespeichert als Umgebungsvariable
OpenAI-kompatible Basis-URL	https://api.novita.ai/openai
Chat-Completions-Endpunkt	POST https://api.novita.ai/openai/v1/chat/completions
Modell-ID	tencent/hy3

Verwenden Sie tencent/hy3 in allen API-Aufrufen. Verwenden Sie in der benutzerseitigen UI oder Dokumentation den Anzeigenamen „Hy3“.

Das Novita AI Dokumentationsverzeichnis listet die OpenAI-kompatible Basis-URL auf, und die Chat-Completions-API-Referenz dokumentiert die vollständige Anfrage- und Antwortstruktur.

Schritt 3: Überprüfen Sie Preise, Limits und Modelldetails

Aktuelle Werte von der Hy3-Modellseite auf Novita AI:

Feld	Wert
Anzeigename	Hy3
API-Modell-ID	tencent/hy3
Modellserie	Hunyuan
Architektur	MoE, 295B gesamt / 21B aktiv
Endpunkt	chat/completions
Eingabemodalitäten	Text
Ausgabemodalitäten	Text
Kontextfenster	262.144 Token
Max. Ausgabe-Token	262.144 Token
Features	Serverlos, Funktionsaufrufe, strukturierte Ausgaben, Reasoning
Eingabepreis	Aufgeführt mit $0 / M Token (aktuellen Preis auf Modellseite prüfen)
Ausgabepreis	Aufgeführt mit $0 / M Token (aktuellen Preis auf Modellseite prüfen)

Ratenbegrenzungen skalieren nach Kontostufe (T1–T5) und werden in Anfragen pro Minute (RPM) und Token pro Minute (TPM) gemessen. Aktuelle Stufenschwellen und Limits sind in der Novita AI Ratenbegrenzungs-Dokumentation aufgeführt.

Preise und Ratenbegrenzungen können sich ändern. Überprüfen Sie die Hy3-Modellseite und die Novita AI Preisseite, bevor Sie sich auf Kostenschätzungen festlegen.

Schritt 4: Senden Sie Ihre erste Anfrage

Beginnen Sie mit einer einfachen Textanfrage, um Authentifizierung, Modell-Routing und Antwort-Parsing zu bestätigen. Halten Sie den Prompt kurz, sodass Sie Konnektivität testen, nicht die Ausgabequalität.

cURL-Beispiel

curl "https://api.novita.ai/openai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${NOVITA_API_KEY}" \
  -d '{
    "model": "tencent/hy3",
    "messages": [
      {
        "role": "system",
        "content": "You are a concise technical assistant."
      },
      {
        "role": "user",
        "content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences."
      }
    ],
    "max_tokens": 256,
    "temperature": 0.3
  }'

Eine erfolgreiche Antwort gibt die Standard-Chat-Completions-Struktur zurück: ein choices-Array, eine Nachricht mit content, Metadaten zu Modell und Erstellung sowie ein usage-Objekt mit Prompt-, Completion- und Gesamttokenanzahlen.

Verwenden Sie diesen Rauchtest, um Folgendes zu überprüfen:

• Der API-Schlüssel ist gültig und der Autorisierungs-Header ist korrekt formatiert.
• Die Modell-ID tencent/hy3 wird ohne 404- oder Modell-nicht-gefunden-Fehler akzeptiert.
• Ihr Client kann choices[0].message.content parsen.
• Die Token-Nutzung wird protokolliert, sodass Sie die Kosten ab der ersten Anfrage überwachen können.

Python-Beispiel

Das OpenAI Python SDK funktioniert mit Novita AI, wenn Sie die Basis-URL festlegen:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a concise technical assistant."},
        {
            "role": "user",
            "content": "Describe the main trade-off between MoE and dense transformer architectures in three sentences.",
        },
    ],
    max_tokens=256,
    temperature=0.3,
)

print(response.choices[0].message.content)
print("Tokens used:", response.usage.total_tokens)

Schritt 5: Lesen Sie die Antwort

Die Antwort folgt dem Standard-OpenAI-Chat-Completions-Format:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1751000000,
  "model": "tencent/hy3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "MoE models activate only a fraction of their total parameters..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 52,
    "completion_tokens": 80,
    "total_tokens": 132
  }
}

Das Feld finish_reason gibt an, warum die Generierung gestoppt wurde. stop bedeutet, dass das Modell ein natürliches Ende erreicht hat. length bedeutet, dass max_tokens erreicht wurde. Wenn Sie bei kurzen Prompts length sehen, erhöhen Sie max_tokens oder reduzieren Sie den Prompt.

Wichtige Parameter

Parameter	Typ	Effekt
model	string	Muss tencent/hy3 sein
messages	array	Gesprächsverlauf. system, user und assistant-Rollen werden unterstützt.
max_tokens	integer	Obergrenze für Ausgabe-Token. Explizit setzen; der Standardwert kann je nach Client variieren.
temperature	float (0–2)	Niedrigere Werte erzeugen deterministischere Ausgaben. Verwenden Sie 0,1–0,3 für Code und sachliche Aufgaben; 0,7–1,0 für kreative oder abwechslungsreiche Ausgaben.
top_p	float (0–1)	Alternative zu temperature für das Sampling. Vermeiden Sie es, beide gleichzeitig zu setzen.
stream	boolean	Setzen Sie true, um Token als Stream zu empfangen. Erfordert Server-Sent-Event-Handling auf Ihrem Client.
tools	array	Tool-Definitionen für Funktionsaufrufe. Siehe den Abschnitt zu Funktionsaufrufen unten.
tool_choice	string oder object	Steuert, welches Tool das Modell aufruft. "auto" überlässt die Entscheidung dem Modell.

Für Workloads mit langem Kontext unterstützt Hy3 bis zu 262.144 Eingabe-Token. Budgetieren Sie die Token-Nutzung pro Aufruf und überwachen Sie die kumulierten Kosten, wenn Sie große Dokumente oder lange Gesprächsverläufe verarbeiten.

Funktionsaufrufe

Hy3 unterstützt Funktionsaufrufe über den Parameter tools. Verwenden Sie ihn, wenn das Modell strukturierte Argumente anstelle von Prosa zurückgeben soll – um eine Anfrage an eine bestimmte Aktion weiterzuleiten, Benutzereingaben in typisierte Felder zu parsen oder einen mehrstufigen Workflow zu steuern.

import os
import json
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "search_knowledge_base",
            "description": "Search a product knowledge base for answers to customer queries.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The customer's question or topic to search for.",
                    },
                    "max_results": {
                        "type": "integer",
                        "description": "Maximum number of results to return. Default is 5.",
                    },
                },
                "required": ["query"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a customer support assistant. Use the search tool to find relevant answers."},
        {
            "role": "user",
            "content": "What is your return policy for electronics purchased in the last 30 days?",
        },
    ],
    tools=tools,
    tool_choice="auto",
    temperature=0.1,
)

message = response.choices[0].message
if message.tool_calls:
    for call in message.tool_calls:
        print(f"Tool: {call.function.name}")
        args = json.loads(call.function.arguments)
        print(f"Arguments: {args}")
else:
    print(message.content)

Wenn das Modell einen Tool-Aufruf zurückgibt, führt Ihre Anwendung die Funktion aus und sendet das Ergebnis dann zurück in die Unterhaltung:

# After executing your search function, send the result back
tool_result = "Returns accepted within 30 days with original receipt. Electronics must be unopened."

follow_up = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {"role": "system", "content": "You are a customer support assistant."},
        {"role": "user", "content": "What is your return policy for electronics purchased in the last 30 days?"},
        message,  # the assistant's tool call message
        {
            "role": "tool",
            "tool_call_id": message.tool_calls[0].id,
            "content": tool_result,
        },
    ],
    temperature=0.1,
)

print(follow_up.choices[0].message.content)

Testen Sie Ihre Tool-Schemas mit repräsentativen Abfragen, bevor Sie Produktionsdatenverkehr weiterleiten. Die Qualität der Funktionsargument-Extraktion hängt davon ab, wie klar Sie jeden Parameter und seine erwarteten Werte beschreiben.

Reasoning-Modus

Hy3 listet Reasoning als unterstütztes Feature auf der Novita AI-Modellseite. Reasoning-fähige Modelle denken ein Problem durch, bevor sie eine endgültige Antwort erstellen, was die Ausgabequalität bei komplexen mehrstufigen Problemen verbessern kann – Fehlersuche in Code, mehrstufige Mathematik, Langdokument-Analyse und Planungsaufgaben.

Die Novita AI Chat-Completions-API unterstützt Reasoning-bezogene Parameter (separate_reasoning, enable_thinking) für ausgewählte Modelle. Ob diese Parameter von tencent/hy3 akzeptiert werden und das genaue Anfrageformat sind in der aktuellen Novita-Dokumentation nicht bestätigt. Bevor Sie Reasoning-Verhalten in einen Produktionsworkload mit Hy3 einbauen, führen Sie einen Testaufruf durch und prüfen Sie, ob die Antwort ein Feld reasoning_content in choices[0].message enthält.

Für verifizierte Parameternamen und unterstützte Modell-IDs siehe die Novita AI Chat-Completions-API-Referenz und den Leitfaden zu Reasoning-Modellen.

Verwendung des Langkontexts

Das 256K-Kontextfenster von Hy3 ist ein praktischer Vorteil für Aufgaben, die erfordern, einen großen Textkörper in einem einzigen Aufruf zu halten. Anwendungsfälle, bei denen dies relevant ist:

• Dokumentenanalyse: Senden Sie einen vollständigen Vertrag, ein Forschungspapier oder eine Spezifikation als Kontext und stellen Sie gezielte Fragen ohne Aufteilung.
• Codebase-Review: Übergeben Sie eine große Datei oder mehrere zusammengehörige Dateien und bitten Sie um Architekturbeobachtungen, Fehlermuster oder Refactoring-Vorschläge.
• Langer Gesprächsverlauf: Agentische Workflows, die viele Runden ansammeln, können länger im Kontext bleiben, bevor eine Zusammenfassung oder Kürzung erforderlich ist.

Für Langkontext-Aufrufe setzen Sie max_tokens explizit basierend auf Ihrer erwarteten Ausgabelänge. Das Senden von 200K Token Eingabe und das Belassen des Ausgabe-Token-Budgets auf dem Standardwert verschwendet Kontextbudget und kann zu abgeschnittenen Antworten führen.

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novita.ai/openai",
    api_key=os.environ["NOVITA_API_KEY"],
)

with open("large_document.txt") as f:
    document_text = f.read()

response = client.chat.completions.create(
    model="tencent/hy3",
    messages=[
        {
            "role": "system",
            "content": "You are a document analysis assistant. Provide specific, referenced answers.",
        },
        {
            "role": "user",
            "content": f"Here is the document:\n\n{document_text}\n\nSummarize the key obligations and deadlines in this document.",
        },
    ],
    max_tokens=1024,
    temperature=0.2,
)

print(response.choices[0].message.content)

Überwachen Sie usage.prompt_tokens in der Antwort, um zu verfolgen, wie viele Token Ihre Eingaben verbrauchen. Für Workloads, die wiederholt denselben System-Prompt oder dieselbe Dokument-Präambel senden, hängt die Ratenbegrenzungs- und Kostenplanung von der tatsächlichen Prompt-Token-Anzahl ab, nicht nur von der Zeichenanzahl des Dokuments.

Fehlerbehebung

401 Unauthorized: Der API-Schlüssel fehlt, ist abgelaufen oder falsch formatiert. Überprüfen Sie, ob der Authorization-Header Bearer <your_key> mit einem Leerzeichen und ohne zusätzliche Zeichen lautet.

404 oder Modell nicht gefunden: Die Modell-ID ist falsch. Bestätigen Sie, dass die genaue Zeichenfolge tencent/hy3 mit der auf der Novita AI-Modellseite angezeigten ID übereinstimmt. Modell-IDs unterscheiden zwischen Groß- und Kleinschreibung.

429 Rate Limit: Sie haben die Anfragen oder Token pro Minute für Ihre Stufe überschritten. Fügen Sie Wiederholungslogik mit exponentiellem Backoff hinzu oder beantragen Sie eine höhere Stufe, wenn Ihr Workload dies dauerhaft erfordert.

finish_reason: length: Die Antwort wurde vorzeitig abgeschnitten, da sie max_tokens erreicht hat. Erhöhen Sie den Wert von max_tokens, wenn Sie längere Ausgaben benötigen, aber denken Sie daran, dass Ausgabe-Token Kosten und Latenz beeinflussen.

Langsame erste Antwort: Große Modellbereitstellungen können eine kurze Kaltstart-Latenz bei der ersten Anfrage aufweisen. Nachfolgende Anfragen an denselben Endpunkt sind in der Regel schneller. Wenn Latenz eine harte Anforderung ist, testen Sie den Durchsatz auf Ihrem Zielparallelitätsniveau vor dem Produktionsstart.

Tool-Aufruf gibt unerwartete Argumente zurück: Überarbeiten Sie Ihr Tool-Schema. Fügen Sie spezifischere Beschreibungen zu jedem Parameter hinzu, fügen Sie Beispielwerte in das Beschreibungsfeld ein und listen Sie erforderliche Felder explizit auf. Testen Sie zuerst mit vereinfachten Schemas und fügen Sie dann Komplexität hinzu.

FAQ

Ist Hy3 auf Novita AI verfügbar?

Ja. Novita AI listet Hy3 als Serverless LLM mit der API-Modell-ID tencent/hy3.

Was ist die korrekte Modell-ID?

Verwenden Sie tencent/hy3 in allen API-Aufrufen. Verwenden Sie „Hy3“ in benutzerseitigen Texten.

Welchen Endpunkt sollte ich verwenden?

Verwenden Sie den OpenAI-kompatiblen Chat-Completions-Endpunkt: POST https://api.novita.ai/openai/v1/chat/completions. Setzen Sie die Basis-URL auf https://api.novita.ai/openai, wenn Sie das OpenAI SDK verwenden.

Wie groß ist das Kontextfenster?

Hy3 unterstützt ein Kontextfenster von 262.144 Token und bis zu 262.144 Ausgabe-Token, wie auf der Novita AI-Modellseite aufgeführt.

Unterstützt Hy3 Funktionsaufrufe?

Ja. Hy3 unterstützt Funktionsaufrufe über den Parameter tools in der Chat-Completions-Anfrage. Novita listet Funktionsaufrufe und strukturierte Ausgaben als unterstützte Features.

Unterstützt Hy3 Reasoning?

Reasoning ist als Feature auf der Novita AI-Modellseite aufgeführt. Die spezifischen Anforderungsparameter zum Aktivieren von Reasoning mit tencent/hy3 sind in der aktuellen Novita-Dokumentation nicht bestätigt. Überprüfen Sie die Novita AI Chat-Completions-API-Referenz und führen Sie einen Testaufruf durch, um das Parameterformat zu überprüfen, bevor Sie Reasoning-Verhalten in die Produktion einbauen.

Welche Eingaben akzeptiert Hy3?

Hy3 akzeptiert nur Texteingaben. Es listet keine Bild- oder Video-Modalitäten auf der Novita AI-Modellseite.

Was ist die Architektur von Hy3?

Hy3 verwendet eine MoE-Architektur (Mixture of Experts) mit 295B Gesamtparametern und 21B aktiven Parametern pro Vorwärtspass. Dies ermöglicht es, Anfragen mit großem Kontext zu geringeren Rechenkosten im Vergleich zu dichten Modellen ähnlicher Qualität zu bedienen.

Wie erhalte ich eine höhere Ratenbegrenzung?

Ratenbegrenzungen skalieren nach Kontostufe. Aktuelle Stufenschwellen und Limits sind in der Novita AI Ratenbegrenzungs-Dokumentation aufgeführt. Kontaktieren Sie den Novita AI-Support für Upgrade-Optionen.

Empfohlene Artikel

• Funktionsaufrufe und strukturierte Ausgaben auf Novita AI
• Wie Sie einen Deep-Search-Agentic-Workflow mit LangChain und Novita AIs LLM-API entwickeln
• Hunyuan Image 3 API auf Novita AI: Text-zu-Bild-Generierungsleitfaden