Mastra

ابنِ وكلاء ذكاء اصطناعي وأدوات وسير عمل بلغة TypeScript باستخدام Mastra مع نماذج دردشة Venice الخاصة وغير الخاضعة للرقابة والمتوافقة مع OpenAI كمزوّد للنموذج اللغوي الكبير (LLM).

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

​

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

• Node.js 22.18 أو أحدث
• مفتاح Venice API

​

إنشاء مشروع Mastra

npm

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 المتاحة وتحقق من قدراتها قبل اختيار نموذج لاستدعاء الأدوات أو الرؤية أو المخرجات المهيكلة.

​

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

الـ API يعيد 401 Unauthorized

تأكد من وجود VENICE_API_KEY في البيئة التي يعمل فيها Mastra، ثم أعِد تشغيل خادم التطوير بعد تعديل .env.

الـ API يُفيد بأن النموذج غير موجود

استخدم معرّف النموذج تمامًا كما هو معروض في صفحة النماذج. في Mastra، أضف إليه البادئة venice/، مثل venice/venice-uncensored.

الطلبات تعيد 404 Not Found

اضبط عنوان URL للنموذج على https://api.venice.ai/api/v1. لا تستخدم نقطة النهاية الكاملة /chat/completions.

الوكيل لا يستدعي أداته

اختر نموذجًا يدعم استدعاء الدوال، ووضّح متى ينبغي للوكيل استخدام الأداة ضمن تعليماته، وعرّف الأداة باستخدام createTool().

وثائق Mastra

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

نماذج Venice

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