الانتقال إلى المحتوى الرئيسي
Mastra هو إطار عمل بلغة TypeScript لبناء وكلاء الذكاء الاصطناعي وأدواتهم وسير العمل. اربطه بـ Venice عبر تهيئة نقطة نهاية نموذج مخصّصة متوافقة مع OpenAI.

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

إنشاء مشروع Mastra

npm create mastra@latest
pnpm create mastra
yarn create mastra
bunx create-mastra
أضف مفتاح Venice API إلى ملف .env الخاص بالمشروع الذي تم إنشاؤه:
VENICE_API_KEY=your-venice-api-key
احتفظ بملف .env خارج إدارة الإصدارات. لا تكشف مفتاح Venice API الخاص بك في التعليمات البرمجية التي تعمل في المتصفح.

إنشاء وكيل مدعوم بـ Venice

أنشئ وكيلًا ووجّه تهيئة النموذج الخاصة به إلى Venice API:
// src/mastra/agents/venice-agent.ts
import { Agent } from '@mastra/core/agent'

export const veniceAgent = new Agent({
  id: 'venice-agent',
  name: 'Venice Agent',
  instructions: `
    You are a concise, privacy-respecting assistant.
    Give accurate answers and say when you are uncertain.
  `,
  model: {
    id: 'venice/venice-uncensored',
    url: 'https://api.venice.ai/api/v1',
    apiKey: process.env.VENICE_API_KEY,
  },
})
الجزء الأول من id هو تسمية التوجيه في Mastra. يرسل Mastra بقية معرّف النموذج، وهو venice-uncensored، إلى Venice.
اضبط url على عنوان URL الأساسي للـ API الموضح أعلاه. لا تُلحق /chat/completions؛ فـ Mastra يضيف هذا المسار.
سجّل الوكيل في نسخة Mastra الخاصة بك:
// src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { veniceAgent } from './agents/venice-agent'

export const mastra = new Mastra({
  agents: { veniceAgent },
})
شغّل خادم التطوير وافتح عنوان URL الظاهر في الطرفية لاختبار الوكيل داخل Mastra Studio:
npm run dev

توليد استجابة

استرجع الوكيل المسجّل واستدعِ generate():
import { mastra } from './src/mastra/index'

const agent = mastra.getAgentById('venice-agent')
const result = await agent.generate(
  'Explain why zero data retention matters in two sentences.',
)

console.log(result.text)
console.log(result.usage)

بث استجابة

استخدم stream() عندما ترغب في عرض المخرجات لحظة وصولها:
const agent = mastra.getAgentById('venice-agent')
const result = await agent.stream(
  'Write a short poem about private AI inference.',
)

for await (const chunk of result.textStream) {
  process.stdout.write(chunk)
}

إضافة الأدوات

تستخدم أدوات Mastra مخططات Zod للتحقق من مدخلاتها ومخرجاتها. استخدم نموذج Venice يدعم استدعاء الدوال عند إرفاق أدوات بوكيل.
// src/mastra/tools/model-info.ts
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const modelInfoTool = createTool({
  id: 'model-info',
  description: 'Returns a short description of a Venice model',
  inputSchema: z.object({
    model: z.string().describe('A Venice model ID'),
  }),
  outputSchema: z.object({
    description: z.string(),
  }),
  execute: async ({ model }) => {
    const descriptions: Record<string, string> = {
      'venice-uncensored': 'A fast, uncensored general-purpose model.',
      'zai-org-glm-5-1': 'A private model for reasoning and tool use.',
    }

    return {
      description: descriptions[model] ?? `No description found for ${model}.`,
    }
  },
})
أرفق الأداة بوكيل:
// src/mastra/agents/model-guide-agent.ts
import { Agent } from '@mastra/core/agent'
import { modelInfoTool } from '../tools/model-info'

export const modelGuideAgent = new Agent({
  id: 'model-guide-agent',
  name: 'Venice Model Guide',
  instructions: 'Help users choose a Venice model. Use modelInfoTool when needed.',
  model: {
    id: 'venice/zai-org-glm-5-1',
    url: 'https://api.venice.ai/api/v1',
    apiKey: process.env.VENICE_API_KEY,
  },
  tools: { modelInfoTool },
})

توليد مخرجات مهيكلة

مرّر مخطط Zod عبر structuredOutput لاستقبال بيانات موثّقة:
import { z } from 'zod'

const result = await veniceAgent.generate(
  'Compare private and data-retaining AI inference.',
  {
    structuredOutput: {
      schema: z.object({
        summary: z.string(),
        privacyBenefits: z.array(z.string()),
        recommendation: z.string(),
      }),
    },
  },
)

console.log(result.object)
إذا كان النموذج المختار لا يدعم وضع المخرجات المهيكلة في الـ API، فاضبط jsonPromptInjection: true داخل structuredOutput ليقوم Mastra بإضافة المخطط إلى التوجيه (prompt) بدلًا من ذلك.

تغيير النماذج

لاستخدام نموذج نصي آخر من Venice، حافظ على بادئة التوجيه venice/ واستبدل بقية معرّف النموذج:
model: {
  id: 'venice/qwen3-5-9b',
  url: 'https://api.venice.ai/api/v1',
  apiKey: process.env.VENICE_API_KEY,
}
تصفّح نماذج Venice المتاحة وتحقق من قدراتها قبل اختيار نموذج لاستدعاء الأدوات أو الرؤية أو المخرجات المهيكلة.

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

تأكد من وجود VENICE_API_KEY في البيئة التي يعمل فيها Mastra، ثم أعِد تشغيل خادم التطوير بعد تعديل .env.
استخدم معرّف النموذج تمامًا كما هو معروض في صفحة النماذج. في Mastra، أضف إليه البادئة venice/، مثل venice/venice-uncensored.
اضبط عنوان URL للنموذج على https://api.venice.ai/api/v1. لا تستخدم نقطة النهاية الكاملة /chat/completions.
اختر نموذجًا يدعم استدعاء الدوال، ووضّح متى ينبغي للوكيل استخدام الأداة ضمن تعليماته، وعرّف الأداة باستخدام createTool().

وثائق Mastra

تعرّف على المزيد حول وكلاء Mastra وأدواتها وسير العمل

نماذج Venice

تصفّح النماذج والقدرات المدعومة