> ## 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

> ابنِ وكلاء Rust مُصنَّفين نوعيًا باستخدام موفّر Venice الأصلي في Rig للأدوات، والمخرجات المُهيكلة، والبث، والتضمينات، و venice_parameters.

[Rig](https://rig.rs/) هي مكتبة Rust لبناء تطبيقات ووكلاء نماذج اللغة الكبيرة. اعتبارًا من الإصدار 0.42، تأتي Rig مع موفّر [`venice`](https://docs.rs/rig/latest/rig/providers/venice/) أصلي — إتمامات المحادثة، والبث، والأدوات، والمخرجات المُهيكلة، والتضمينات، والتفريغ الصوتي، وتوليد الصور، والكلام — موصولةً بواجهة برمجة تطبيقات Venice مباشرةً بدلًا من تمريرها عبر عميل OpenAI.

إذا كنت تريد وسيط Axum خامًا بدلًا من إطار عمل وكلاء، راجع [بناء بوابة LLM بلغة Rust](/guides/projects/rust-llm-gateway).

## المتطلبات الأساسية

* سلسلة أدوات Rust مستقرة حديثة (يستخدم Rig 0.42 إصدار 2024)
* Rig 0.42 أو أحدث
* [مفتاح Venice API](/guides/getting-started/generating-api-key)

## الإعداد

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

أضف مفتاح Venice API إلى البيئة. اختياريًا، يمكنك تجاوز مضيف API عبر `VENICE_BASE_URL` (يستخدم الموفّر افتراضيًا `https://api.venice.ai/api/v1`):

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

<Warning>
  احتفظ بمفاتيح API خارج نظام إدارة الشيفرة. يُفضَّل استخدام متغيرات البيئة أو مدير أسرار في الإنتاج.
</Warning>

## تهيئة عميل Venice

يقرأ `venice::Client::from_env()` قيمة `VENICE_API_KEY`. أدرج `ProviderClient` ضمن النطاق:

```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>
  يُفضَّل استخدام `venice::Client` بدلًا من توجيه عميل OpenAI في Rig نحو Venice. العميل الافتراضي `openai::Client` يستهدف واجهة Responses API من OpenAI. أما موفّر Venice فيتحدث لغة `/chat/completions` ويكشف [`VeniceParameters`](#venice-specific-parameters).
</Note>

تأخذ المقتطفات أدناه `&venice::Client` من `from_env()`. ثوابت الحزمة مثل `venice::QWEN3_5_9B` هي نقطة بداية — تحقق من المعرّفات الحالية عبر [`GET /models`](/api-reference/endpoint/models/list).

## بث الاستجابة

يُرجع `stream_prompt` طلبًا يمكنك استخدام `.await` عليه للحصول على تدفق. استخدم `rig::agent::stream_to_stdout` لطباعة الرموز فور وصولها:

```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(())
}
```

لا تُضف `?` بعد `.await` على `stream_prompt` — فهي تُنتج التدفق مباشرةً، وليس `Result`.

## المخرجات المُهيكلة

استخدم مُستخرِجًا (extractor) مع نوع `JsonSchema` للتحقق من صحة إجابة النموذج:

```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?)
}
```

تصفّح النماذج التي تدعم [الاستجابات المُهيكلة](/guides/features/structured-responses) و[استدعاء الدوال](/guides/features/function-calling) قبل الاعتماد على الاستخراج المستند إلى الأدوات في الإنتاج.

## الأدوات

عرِّف أداة باستخدام `#[rig_tool]` (المُضمَّنة مع ميزة `derive` الافتراضية في Rig). النوع المُولَّد هو اسم الدالة بصيغة 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?)
}
```

يمكنك أيضًا تنفيذ `rig::tool::Tool` يدويًا عندما تحتاج إلى أنواع وسيطات مخصّصة أو معالجة مخصّصة للأخطاء. راجع [توثيق الأدوات في Rig](https://docs.rig.rs/docs/concepts/tools).

## التضمينات

```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 حقل `dimensions` في OpenAI. استخدم `embedding_model_with_ndims` عندما تريد عرضًا محددًا بدلًا من الحجم الأصلي للنموذج.

## المعاملات الخاصة بـ Venice

مرِّر الخيارات الخاصة بـ Venice عبر `VeniceParameters` وادمجها مع `additional_params`. على سبيل المثال، لتفعيل البحث المدمج على الويب:

```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?)
}
```

للاحتفاظ باستشهادات البحث على الويب (وكتلة `cost` لكل طلب)، استدعِ `raw_completion` على نموذج الإتمام. فمسار الوكيل المُطبَّع يُسقط تلك الحقول الخاصة بـ Venice:

```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` أيضًا مُعرِّفات الشخصيات (character slugs)، وضوابط التفكير، وكشط الويب، والبحث في X، وما إذا كان يجب تضمين موجّه النظام الافتراضي في Venice. راجع [مواصفات API](/api-reference/api-spec) للاطلاع على القائمة الكاملة لـ `venice_parameters`.

## قدرات أخرى

يقود `venice::Client` نفسه أيضًا:

* **التفريغ الصوتي** — `client.transcription_model(venice::WHISPER_LARGE_V3)`
* **توليد الصور** — `client.image_generation_model(...)` (فعِّل ميزة `image` في Rig)
* **الكلام** — `client.audio_generation_model(venice::TTS_KOKORO)` (فعِّل ميزة `audio` في Rig)

الفيديو، والموسيقى، وتحرير الصور، و `/augment/*`، و crypto RPC ليس لها سمة (trait) في Rig وغير مغلفة. استدعِ نقاط نهاية Venice تلك مباشرةً.

## ميزة الخصوصية

كثيرًا ما تُستخدم Rig لوكلاء يتعاملون مع بيانات التطبيق، أو سياق المستخدم، أو الأدوات الداخلية. اقترانها بـ Venice يُبقي هذا العمل ضمن استدلال خاص وغير خاضع للرقابة:

* **عدم الاحتفاظ بالبيانات** على النماذج الخاصة — لا يُحتفظ بالموجّهات وحمولات الأدوات بعد الطلب
* **تحليل غير خاضع للرقابة** عندما يحتاج الوكلاء إلى نقد صريح أو اختبار اختراق (red-teaming)
* **موفّر أصلي مدمج** حتى لا تضطر إلى إعادة ربط أنواع OpenAI بلهجة Venice

## استكشاف الأخطاء وإصلاحها

<AccordionGroup>
  <Accordion title="401 غير مصرَّح به">
    تأكّد من ضبط `VENICE_API_KEY` في العملية التي تشغّل الوكيل. أعد تشغيل الصدفة أو العملية بعد تغيير متغيرات البيئة. لا يقرأ `from_env()` قيمة `OPENAI_API_KEY`.
  </Accordion>

  <Accordion title="النموذج غير موجود أو أخطاء غير متوقعة في نقطة النهاية">
    استخدم مُعرِّف نموذج حديثًا من [صفحة النماذج](/models/overview) أو `GET /models`. قد تتأخر ثوابت الحزمة مثل `venice::QWEN3_5_9B` عن الكتالوج المباشر.
  </Accordion>

  <Accordion title="فشل واجهة Responses API">
    استخدم `venice::Client`، وليس `openai::Client`. عميل OpenAI يستهدف افتراضيًا Responses API، وهي في مرحلة ألفا فقط على Venice.
  </Accordion>

  <Accordion title="تجاهُل الأدوات أو المخرجات المُهيكلة">
    اختر نموذجًا يدعم [استدعاء الدوال](/guides/features/function-calling)، ووضّح متى ينبغي تشغيل الأدوات في التمهيد (preamble)، واحرص على أن تكون أوصاف الأدوات دقيقة — إذ تبني Rig مخططات JSON من توقيعات `#[rig_tool]` والتوثيق.
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="توثيق Rig" icon="book" href="https://docs.rig.rs/">
    الوكلاء، والأدوات، والمُستخرِجات، والموفّرون
  </Card>

  <Card title="نماذج Venice" icon="database" href="/models/overview">
    تصفّح النماذج والقدرات المدعومة
  </Card>
</CardGroup>