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

# تكامل PydanticAI

> ابنِ وكلاء Python مُنمَّطة مع PydanticAI باستخدام نماذج المحادثة الخاصة والمتوافقة مع OpenAI من Venice، للأدوات والمخرجات المُهيكَلة والبثّ.

[PydanticAI](https://ai.pydantic.dev/) هو إطار عمل للوكلاء بلغة Python من فريق Pydantic. يمنحك تبعيّات مُنمَّطة، واستدعاء أدوات، ومخرجات مُهيكَلة، وبثًّا فوق مزوّدي LLM. يعمل Venice كواجهة خلفية متوافقة مع OpenAI — وجّه `OpenAIChatModel` إلى Venice واستمر في استخدام باقي واجهة PydanticAI كالمعتاد.

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

* Python 3.9 أو أحدث
* [مفتاح Venice API](/guides/getting-started/generating-api-key)

## الإعداد

ثبّت PydanticAI مع دعم OpenAI:

<CodeGroup>
  ```bash pip theme={"system"}
  pip install "pydantic-ai-slim[openai]"
  ```

  ```bash uv theme={"system"}
  uv add "pydantic-ai-slim[openai]"
  ```
</CodeGroup>

يمكنك أيضًا تثبيت الحزمة الكاملة `pydantic-ai`، التي تتضمن إضافات OpenAI.

أضف مفتاح Venice API إلى البيئة:

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

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

## اضبط Venice كمزوّد للنموذج

يتحدث Venice واجهة OpenAI Chat Completions. استخدم `OpenAIChatModel` مع `OpenAIProvider` وعنوان Venice الأساسي:

```python theme={"system"}
import os

from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "venice-uncensored",
    provider=OpenAIProvider(
        base_url="https://api.venice.ai/api/v1",
        api_key=os.environ["VENICE_API_KEY"],
    ),
)

agent = Agent(
    model,
    instructions="أنت مساعد موجز ويحترم الخصوصية.",
)
```

<Note>
  استخدم `OpenAIChatModel` (Chat Completions)، وليس `OpenAIResponsesModel` / اختصار `openai:`. مسار التوافق الأساسي في Venice هو `/chat/completions`. تثبيت Chat Completions يتفادى سلوكيات خاصة بـ Responses تستخدمها نماذج OpenAI الافتراضية في إصدارات PydanticAI الأحدث.
</Note>

### متغيرات البيئة

يقرأ `OpenAIProvider` أيضًا `OPENAI_API_KEY` و`OPENAI_BASE_URL`. يمكنك ضبط Venice بهذه الطريقة بدلًا من تمرير الوسائط في الكود:

```bash theme={"system"}
export OPENAI_API_KEY=your-venice-api-key
export OPENAI_BASE_URL=https://api.venice.ai/api/v1
```

```python theme={"system"}
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel

agent = Agent(
    OpenAIChatModel("venice-uncensored"),
    instructions="أنت مساعد موجز ويحترم الخصوصية.",
)
```

## شغّل وكيلًا

```python theme={"system"}
result = agent.run_sync("اشرح الاحتفاظ الصفري للبيانات في جملتين.")
print(result.output)
print(result.usage)
```

الاستخدام غير المتزامن يتبع النمط ذاته مع `await agent.run(...)`:

```python theme={"system"}
import asyncio

async def main() -> None:
    result = await agent.run("ما مستويات الخصوصية التي يقدمها Venice؟")
    print(result.output)

asyncio.run(main())
```

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

استخدم `run_stream` عندما ترغب في استقبال الرموز فور وصولها:

```python theme={"system"}
import asyncio

async def main() -> None:
    async with agent.run_stream("اكتب قصيدة قصيرة عن الذكاء الاصطناعي الخاص.") as response:
        async for text in response.stream_text():
            print(text, end="", flush=True)

asyncio.run(main())
```

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

مرّر نموذج Pydantic كـ `output_type` للتحقق من الإجابة النهائية للوكيل:

```python theme={"system"}
import os

from pydantic import BaseModel, Field
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider


class PrivacySummary(BaseModel):
    summary: str = Field(description="نظرة عامة بجملة واحدة")
    benefits: list[str] = Field(description="فوائد الخصوصية الرئيسية")
    recommendation: str = Field(description="متى يُختار هذا النهج")


model = OpenAIChatModel(
    "zai-org-glm-5-1",
    provider=OpenAIProvider(
        base_url="https://api.venice.ai/api/v1",
        api_key=os.environ["VENICE_API_KEY"],
    ),
)

agent = Agent(
    model,
    output_type=PrivacySummary,
    instructions="استخرج ملخصًا مُهيكَلًا من طلب المستخدم.",
)

result = agent.run_sync("قارن بين الاستدلال الخاص والمزوّدين الذين يحتفظون بسجلات المحادثات.")
print(result.output.summary)
print(result.output.benefits)
```

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

## الأدوات

سجّل الأدوات باستخدام `@agent.tool_plain` (بدون سياق الوكيل) أو `@agent.tool` (يحتاج إلى `RunContext`):

```python theme={"system"}
import os
from dataclasses import dataclass

from pydantic_ai import Agent, RunContext
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider


@dataclass
class SupportDeps:
    user_id: str


model = OpenAIChatModel(
    "zai-org-glm-5-1",
    provider=OpenAIProvider(
        base_url="https://api.venice.ai/api/v1",
        api_key=os.environ["VENICE_API_KEY"],
    ),
)

agent = Agent(
    model,
    deps_type=SupportDeps,
    instructions="ساعد المستخدمين على اختيار نموذج Venice. استخدم الأدوات عندما تحتاج إلى حقائق.",
)


@agent.tool_plain
def list_budget_models() -> list[str]:
    """أعِد معرّفات نماذج Venice النصية الاقتصادية."""
    return ["venice-uncensored", "qwen3-5-9b"]


@agent.tool
def get_user_tier(ctx: RunContext[SupportDeps]) -> str:
    """أعِد مستوى حساب المتصل."""
    return "pro" if ctx.deps.user_id.startswith("pro_") else "standard"


result = agent.run_sync(
    "ما نماذج Venice الرخيصة التي يجدر بي تجربتها، وما المستوى الذي أنتمي إليه؟",
    deps=SupportDeps(user_id="pro_42"),
)
print(result.output)
```

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

مرّر الخيارات الخاصة بـ Venice عبر `ModelSettings.extra_body`. على سبيل المثال، فعّل بحث الويب المدمج باستخدام `venice_parameters`:

```python theme={"system"}
import os

from pydantic_ai import Agent, ModelSettings
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai import OpenAIProvider

model = OpenAIChatModel(
    "venice-uncensored",
    provider=OpenAIProvider(
        base_url="https://api.venice.ai/api/v1",
        api_key=os.environ["VENICE_API_KEY"],
    ),
)

agent = Agent(
    model,
    model_settings=ModelSettings(
        extra_body={
            "venice_parameters": {
                "enable_web_search": "auto",
            }
        }
    ),
)

result = agent.run_sync("ما أبرز تطورات خصوصية الذكاء الاصطناعي هذا الأسبوع؟")
print(result.output)
```

يمكنك أيضًا تجاوز الإعدادات لكل تشغيل:

```python theme={"system"}
result = agent.run_sync(
    "لخّص عناوين اليوم حول الذكاء الاصطناعي اللامركزي.",
    model_settings=ModelSettings(
        extra_body={"venice_parameters": {"enable_web_search": "on"}}
    ),
)
```

راجع [مواصفات API](/api-reference/api-spec) للاطلاع على القائمة الكاملة لـ `venice_parameters` (كشط الويب، الاستشهادات، الشخصيات، ضوابط التفكير، ومفاتيح التشفير من طرف إلى طرف).

## النماذج الموصى بها

| حالة الاستخدام                        | النموذج                          | السبب                       |
| ------------------------------------- | -------------------------------- | --------------------------- |
| الوكلاء العامّون                      | `venice-uncensored`              | سريع، رخيص، غير مُقيَّد     |
| استدعاء الأدوات / المخرجات المُهيكَلة | `zai-org-glm-5-1`                | نموذج رائد خاص وقوي للوكلاء |
| الاستدلال المعقد                      | `zai-org-glm-5-1`                | تخطيط متعدد الخطوات أفضل    |
| اقتصادي / حجم كبير                    | `qwen3-5-9b`                     | تكلفة منخفضة لكل رمز        |
| الوكلاء المُركّزون على الكود          | `qwen3-coder-480b-a35b-instruct` | مُحسَّن للكود               |

تتغير معرّفات النماذج بمرور الوقت — تأكد من المعرّفات الحالية عبر [`GET /models`](/api-reference/endpoint/models/list) أو [نظرة عامة على النماذج](/models/overview).

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

يُستخدم PydanticAI كثيرًا لبناء وكلاء يتعاملون مع بيانات التطبيقات وسياق المستخدم والأدوات الداخلية. إقرانه بـ Venice يُبقي هذا التدفق على استدلال خاص وغير مُقيَّد:

* **الاحتفاظ الصفري بالبيانات** على النماذج الخاصة — لا تُحفَظ المطالبات وحمولات الأدوات بعد الطلب
* **تحليل غير مُقيَّد** عندما يحتاج الوكلاء إلى نقد صريح أو اختبار من الفريق الأحمر
* **بنية متوافقة مع OpenAI** حتى تتمكن من ترحيل تطبيقات PydanticAI الحالية بمجرد تغيير عنوان المزوّد الأساسي ومفتاح API

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

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

  <Accordion title="النموذج غير موجود أو أخطاء غير متوقعة في نقطة النهاية">
    استخدم معرّف نموذج حديث من [صفحة النماذج](/models/overview). اضبط `base_url` على `https://api.venice.ai/api/v1` دون مسار لاحق — يُضيف PydanticAI `/chat/completions` تلقائيًا.
  </Accordion>

  <Accordion title="فشل Responses API أو بادئة openai:">
    يُفضَّل استخدام `OpenAIChatModel` مع `OpenAIProvider` صريح. تجنّب اختصار الوكيل `openai:` المجرّد، الذي قد يستهدف واجهة Responses من OpenAI بدلًا من Chat Completions.
  </Accordion>

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

<CardGroup cols={2}>
  <Card title="وثائق PydanticAI" icon="book" href="https://ai.pydantic.dev/">
    الوكلاء والأدوات والتبعيات وأنواع المخرجات
  </Card>

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