> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Rig

> Erstellen Sie typisierte Rust-Agenten mit dem nativen Venice-Provider von Rig für Tools, strukturierte Ausgaben, Streaming, Embeddings und venice_parameters.

[Rig](https://rig.rs/) ist eine Rust-Bibliothek zum Erstellen von LLM-Apps und -Agenten. Seit Rig 0.42 wird ein First-Party-Provider [`venice`](https://docs.rs/rig/latest/rig/providers/venice/) ausgeliefert — Chat-Completions, Streaming, Tools, strukturierte Ausgaben, Embeddings, Transkription, Bildgenerierung und Sprache — direkt an die Venice-API angebunden, statt über den OpenAI-Client geleitet zu werden.

Wenn Sie stattdessen einen reinen Axum-Proxy anstelle eines Agenten-Frameworks möchten, siehe [Building a Rust LLM Gateway](/guides/projects/rust-llm-gateway).

## Voraussetzungen

* Eine aktuelle stabile Rust-Toolchain (Rig 0.42 verwendet Edition 2024)
* Rig 0.42 oder neuer
* Ein [Venice-API-Schlüssel](/guides/getting-started/generating-api-key)

## Einrichtung

```bash theme={"system"}
cargo add rig
cargo add tokio --features macros,rt-multi-thread
cargo add serde --features derive
cargo add schemars anyhow
```

Fügen Sie Ihren Venice-API-Schlüssel zur Umgebung hinzu. Optional können Sie den API-Host mit `VENICE_BASE_URL` überschreiben (der Provider verwendet standardmäßig `https://api.venice.ai/api/v1`):

```bash theme={"system"}
export VENICE_API_KEY=your-venice-api-key
```

<Warning>
  Halten Sie API-Schlüssel aus der Versionskontrolle heraus. Bevorzugen Sie in der Produktion Umgebungsvariablen oder einen Secret-Manager.
</Warning>

## Venice-Client konfigurieren

`venice::Client::from_env()` liest `VENICE_API_KEY`. Bringen Sie `ProviderClient` in den Gültigkeitsbereich:

```rust theme={"system"}
use anyhow::Result;
use rig::client::{AgentClientExt, ProviderClient};
use rig::completion::Prompt;
use rig::providers::venice;

#[tokio::main]
async fn main() -> Result<()> {
    let client = venice::Client::from_env()?;

    let agent = client
        .agent(venice::QWEN3_5_9B)
        .preamble("You are a concise, privacy-respecting assistant.")
        .build();

    let response = agent
        .prompt("Explain zero data retention in two sentences.")
        .await?;
    println!("{response}");

    Ok(())
}
```

<Note>
  Bevorzugen Sie `venice::Client`, statt Rigs OpenAI-Client auf Venice zu richten. Der Standard-`openai::Client` zielt auf die Responses-API von OpenAI ab. Der Venice-Provider spricht `/chat/completions` und stellt [`VeniceParameters`](#venice-specific-parameters) bereit.
</Note>

Die folgenden Snippets erhalten einen `&venice::Client` von `from_env()`. Crate-Konstanten wie `venice::QWEN3_5_9B` sind ein Ausgangspunkt — bestätigen Sie aktuelle IDs über [`GET /models`](/api-reference/endpoint/models/list).

## Eine Antwort streamen

`stream_prompt` gibt eine Anfrage zurück, die Sie per `.await` in einen Stream umwandeln. Verwenden Sie `rig::agent::stream_to_stdout`, um Tokens zu drucken, sobald sie eintreffen:

```rust theme={"system"}
use anyhow::Result;
use rig::agent::stream_to_stdout;
use rig::client::AgentClientExt;
use rig::providers::venice;
use rig::streaming::StreamingPrompt;

async fn stream_poem(client: &venice::Client) -> Result<()> {
    let agent = client
        .agent(venice::QWEN3_5_9B)
        .preamble("You are a concise, privacy-respecting assistant.")
        .build();

    let mut stream = agent
        .stream_prompt("Write a short poem about private AI.")
        .await;
    stream_to_stdout(&mut stream).await?;

    Ok(())
}
```

Fügen Sie kein `?` nach dem `.await` von `stream_prompt` hinzu — es liefert direkt den Stream, kein `Result`.

## Strukturierte Ausgabe

Verwenden Sie einen Extraktor mit einem `JsonSchema`-Typ, um die Antwort des Modells zu validieren:

```rust theme={"system"}
use anyhow::Result;
use rig::client::AgentClientExt;
use rig::providers::venice;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

#[derive(Debug, Deserialize, Serialize, JsonSchema)]
struct PrivacySummary {
    /// One-sentence overview
    summary: String,
    /// Key privacy benefits
    benefits: Vec<String>,
    /// When to choose this approach
    recommendation: String,
}

async fn extract_privacy_summary(client: &venice::Client) -> Result<PrivacySummary> {
    let extractor = client
        .extractor::<PrivacySummary>(venice::QWEN3_5_9B)
        .preamble("Extract a structured summary from the user's request.")
        .build();

    Ok(extractor
        .extract("Compare private inference with providers that retain chat logs.")
        .await?)
}
```

Sehen Sie sich Modelle an, die [strukturierte Antworten](/guides/features/structured-responses) und [Function Calling](/guides/features/function-calling) unterstützen, bevor Sie in der Produktion auf tool-basierte Extraktion setzen.

## Tools

Definieren Sie ein Tool mit `#[rig_tool]` (im Standard-`derive`-Feature von Rig enthalten). Der generierte Typ ist der Funktionsname in PascalCase:

```rust theme={"system"}
use anyhow::Result;
use rig::client::AgentClientExt;
use rig::completion::Prompt;
use rig::providers::venice;
use rig::rig_tool;

#[rig_tool(description = "Return budget-friendly Venice text model IDs")]
fn list_budget_models() -> Result<Vec<&'static str>, rig::tool::ToolExecutionError> {
    Ok(vec![venice::QWEN3_5_9B, venice::VENICE_UNCENSORED_1_2])
}

async fn recommend_models(client: &venice::Client) -> Result<String> {
    let agent = client
        .agent(venice::QWEN3_5_9B)
        .preamble("Help users pick a Venice model. Use tools when you need facts.")
        .tool(ListBudgetModels)
        .build();

    Ok(agent
        .prompt("Which cheap Venice models should I try?")
        .await?)
}
```

Sie können `rig::tool::Tool` auch manuell implementieren, wenn Sie eigene Argumenttypen oder Fehlerbehandlung benötigen. Siehe [Rigs Tool-Dokumentation](https://docs.rig.rs/docs/concepts/tools).

## Embeddings

```rust theme={"system"}
use anyhow::Result;
use rig::client::EmbeddingsClient;
use rig::embeddings::EmbeddingModel;
use rig::providers::venice;

async fn embed_documents(client: &venice::Client) -> Result<()> {
    let model = client.embedding_model(venice::TEXT_EMBEDDING_BGE_M3);
    let embeddings = model
        .embed_texts([
            "Venice AI provides private inference.".to_owned(),
            "Zero data retention guaranteed.".to_owned(),
        ])
        .await?;

    for embedding in &embeddings {
        println!("{}: {} dims", embedding.document, embedding.vec.len());
    }

    Ok(())
}
```

Venice berücksichtigt das `dimensions`-Feld von OpenAI. Verwenden Sie `embedding_model_with_ndims`, wenn Sie eine bestimmte Breite anstelle der nativen Modellgröße wünschen.

## Venice-spezifische Parameter

Übergeben Sie Venice-spezifische Optionen über `VeniceParameters` und führen Sie sie mit `additional_params` zusammen. So aktivieren Sie zum Beispiel die integrierte Websuche:

```rust theme={"system"}
use anyhow::Result;
use rig::client::AgentClientExt;
use rig::completion::Prompt;
use rig::providers::venice::{self, VeniceParameters, WebSearchMode};

async fn search_recent_news(client: &venice::Client) -> Result<String> {
    let agent = client
        .agent(venice::QWEN3_5_9B)
        .preamble("You are a concise, privacy-respecting assistant.")
        .additional_params(
            VeniceParameters::new()
                .enable_web_search(WebSearchMode::Auto)
                .into_additional_params(),
        )
        .build();

    Ok(agent
        .prompt("What are notable AI privacy developments this week?")
        .await?)
}
```

Um Web-Such-Zitate (und den `cost`-Block pro Anfrage) zu behalten, rufen Sie `raw_completion` auf dem Completion-Modell auf. Der normalisierte Agenten-Pfad verwirft diese Venice-spezifischen Felder:

```rust theme={"system"}
use anyhow::Result;
use rig::client::CompletionClient;
use rig::completion::CompletionModel;
use rig::providers::venice::{self, VeniceParameters, WebSearchMode};

async fn search_with_citations(client: &venice::Client) -> Result<()> {
    let model = client.completion_model(venice::QWEN3_5_9B);
    let request = model
        .completion_request("In one sentence, what is the Rust programming language?")
        .additional_params(
            VeniceParameters::new()
                .enable_web_search(WebSearchMode::On)
                .enable_web_citations(true)
                .into_additional_params(),
        )
        .build();

    let response = model.raw_completion(request).await?;
    for citation in response.web_search_citations() {
        println!("{} — {}", citation.title, citation.url);
    }

    Ok(())
}
```

`VeniceParameters` deckt außerdem Character-Slugs, Thinking-Steuerung, Web-Scraping, X-Suche und die Frage ab, ob Venices Standard-System-Prompt einbezogen werden soll. Siehe die [API-Spezifikation](/api-reference/api-spec) für die vollständige `venice_parameters`-Liste.

## Weitere Funktionen

Derselbe `venice::Client` treibt außerdem:

* **Transkription** — `client.transcription_model(venice::WHISPER_LARGE_V3)`
* **Bildgenerierung** — `client.image_generation_model(...)` (aktivieren Sie Rigs `image`-Feature)
* **Sprache** — `client.audio_generation_model(venice::TTS_KOKORO)` (aktivieren Sie Rigs `audio`-Feature)

Video, Musik, Bildbearbeitung, `/augment/*` und Krypto-RPC haben kein Rig-Trait und werden nicht gekapselt. Rufen Sie diese Venice-Endpoints direkt auf.

## Datenschutzvorteil

Rig wird häufig für Agenten eingesetzt, die auf Anwendungsdaten, Nutzerkontext oder interne Tools zugreifen. In Kombination mit Venice bleibt dieser Workflow auf privater, unzensierter Inferenz:

* **Zero Data Retention** bei privaten Modellen — Prompts und Tool-Payloads werden nach der Anfrage nicht aufbewahrt
* **Unzensierte Analyse**, wenn Agenten unverblümte Kritik oder Red-Teaming benötigen
* **Ein First-Party-Provider**, sodass Sie OpenAI-Typen nicht auf Venices Dialekt umbiegen müssen

## Fehlerbehebung

<AccordionGroup>
  <Accordion title="401 Unauthorized">
    Vergewissern Sie sich, dass `VENICE_API_KEY` in dem Prozess gesetzt ist, der den Agenten ausführt. Starten Sie die Shell oder den Prozess nach dem Ändern von Umgebungsvariablen neu. `from_env()` liest `OPENAI_API_KEY` nicht.
  </Accordion>

  <Accordion title="Modell nicht gefunden oder unerwartete Endpoint-Fehler">
    Verwenden Sie eine aktuelle Modell-ID von der [Modellseite](/models/overview) oder `GET /models`. Crate-Konstanten wie `venice::QWEN3_5_9B` können hinter dem Live-Katalog zurückbleiben.
  </Accordion>

  <Accordion title="Fehler bei der Responses-API">
    Verwenden Sie `venice::Client`, nicht `openai::Client`. Der OpenAI-Client verwendet standardmäßig die Responses-API, die bei Venice nur Alpha-Status hat.
  </Accordion>

  <Accordion title="Tools oder strukturierte Ausgabe werden ignoriert">
    Wählen Sie ein Modell, das [Function Calling](/guides/features/function-calling) unterstützt, beschreiben Sie in der Preamble, wann Tools ausgeführt werden sollen, und halten Sie die Tool-Beschreibungen präzise — Rig erstellt JSON-Schemas aus `#[rig_tool]`-Signaturen und -Dokumenten.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Rig-Dokumentation" icon="book" href="https://docs.rig.rs/">
    Agenten, Tools, Extraktoren und Provider
  </Card>

  <Card title="Venice-Modelle" icon="database" href="/models/overview">
    Modelle und unterstützte Funktionen durchsuchen
  </Card>
</CardGroup>