README.md

# دليل شامل: الذكاء الاصطناعي المتقدم في Node.js و Shopify Hydrogen

## المقدمة

يقدم هذا الدليل الشامل رؤى عملية حول دمج تقنيات الذكاء الاصطناعي المتقدمة، بما في ذلك البحث الدلالي (Semantic Search) ونماذج اللغة الضخمة (LLMs)، في تطبيقات Node.js ومتاجر Shopify Hydrogen. يهدف هذا المرجع إلى تمكين المطورين من بناء تجارب تجارة إلكترونية أكثر ذكاءً وتخصيصًا، مما يعزز تفاعل العملاء ويزيد من الكفاءة التشغيلية.

---

## دليل عملي: بناء محرك بحث دلالي (Semantic Search) باستخدام Node.js و Shopify Hydrogen

### المقدمة

يمثل البحث الدلالي (Semantic Search) نقلة نوعية من البحث التقليدي القائم على الكلمات المفتاحية إلى البحث القائم على المعنى. باستخدام تقنيات الذكاء الاصطناعي، يمكننا فهم نية المستخدم بشكل أفضل وتقديم نتائج أكثر دقة وذات صلة. يوضح هذا الدليل كيفية بناء محرك بحث دلالي بسيط باستخدام Node.js، والاستفادة من نماذج Embeddings من Hugging Face، وكيفية دمج ذلك مع متجر Shopify Hydrogen.

### المكونات الأساسية

1.  **نماذج Embeddings:** لتحويل النصوص إلى متجهات رقمية (Vector Embeddings) تمثل معناها الدلالي. سنستخدم نماذج `sentence-transformers` من Hugging Face.
2.  **قاعدة بيانات المتجهات (Vector Database):** لتخزين المتجهات والبحث السريع عن المتجهات المتشابهة. يمكن استخدام حلول مثل Pinecone أو Weaviate، أو حتى حلول بسيطة في الذاكرة للمشاريع الصغيرة.
3.  **Node.js Backend:** لمعالجة طلبات البحث، واستدعاء نماذج Embeddings، والتفاعل مع قاعدة بيانات المتجهات.
4.  **Shopify Hydrogen Frontend:** لدمج واجهة البحث وعرض النتائج للمستخدم.

### الخطوات التنفيذية

#### 1. إعداد بيئة Node.js

تأكد من تثبيت Node.js و npm/yarn. سنحتاج إلى مكتبات مثل `axios` للتفاعل مع Hugging Face API، وربما مكتبة للتعامل مع المتجهات (إذا لم يكن هناك دعم أصلي في Node.js Core بعد).

```bash
npm init -y
npm install axios
```

#### 2. استخراج المتجهات (Embeddings) باستخدام Hugging Face

يمكننا استخدام Hugging Face Inference API لتحويل النصوص إلى متجهات. ستحتاج إلى `HF_TOKEN` للحصول على معدل طلبات أعلى.

```javascript
// semanticSearchService.js
import axios from 'axios';

const HF_INFERENCE_API_URL = "https://api-inference.huggingface.co/models/sentence-transformers/all-MiniLM-L6-v2";
const HF_TOKEN = process.env.HF_TOKEN; // تأكد من تعيينه كمتغير بيئة

async function getEmbeddings(texts) {
    try {
        const response = await axios.post(
            HF_INFERENCE_API_URL,
            { inputs: texts },
            {
                headers: {
                    Authorization: `Bearer ${HF_TOKEN}`,
                },
            }
        );
        return response.data;
    } catch (error) {
        console.error("Error getting embeddings:", error.response ? error.response.data : error.message);
        throw error;
    }
}

export { getEmbeddings };
```

#### 3. بناء فهرس البحث الدلالي

لنفترض أن لدينا قائمة بمنتجات Shopify. سنقوم بإنشاء Embeddings لأوصاف هذه المنتجات وتخزينها مع معرفات المنتجات.

```javascript
// indexProducts.js
import { getEmbeddings } from './semanticSearchService.js';

// مثال لمنتجات Shopify (يمكن جلبها من Shopify Storefront API)
const products = [
    { id: 'prod1', title: 'قميص قطني أزرق', description: 'قميص مريح وعصري مصنوع من القطن الخالص.' },
    { id: 'prod2', title: 'بنطال جينز كلاسيكي', description: 'بنطال جينز متين بتصميم كلاسيكي يناسب جميع الأوقات.' },
    { id: 'prod3', title: 'فستان سهرة أنيق', description: 'فستان طويل بتصميم فاخر مثالي للمناسبات الخاصة.' },
];

let productVectors = [];

async function buildSemanticIndex() {
    const descriptions = products.map(p => p.description);
    const embeddings = await getEmbeddings(descriptions);

    productVectors = products.map((p, index) => ({
        id: p.id,
        title: p.title,
        vector: embeddings[index],
    }));
    console.log('Semantic index built successfully.');
    // في تطبيق حقيقي، سيتم تخزين productVectors في قاعدة بيانات متجهات
}

// دالة بسيطة لحساب التشابه (cosine similarity)
function cosineSimilarity(vec1, vec2) {
    const dotProduct = vec1.reduce((sum, a, idx) => sum + a * vec2[idx], 0);
    const magnitude1 = Math.sqrt(vec1.reduce((sum, a) => sum + a * a, 0));
    const magnitude2 = Math.sqrt(vec2.reduce((sum, a) => sum + a * a, 0));
    return dotProduct / (magnitude1 * magnitude2);
}

async function semanticSearch(query) {
    if (productVectors.length === 0) {
        await buildSemanticIndex();
    }

    const queryEmbedding = (await getEmbeddings([query]))[0];

    const results = productVectors.map(p => ({
        ...p,
        similarity: cosineSimilarity(queryEmbedding, p.vector),
    }))
    .sort((a, b) => b.similarity - a.similarity)
    .slice(0, 3); // أفضل 3 نتائج

    return results;
}

// مثال للاستخدام
// semanticSearch('ملابس مريحة').then(res => console.log(res));

export { buildSemanticIndex, semanticSearch };
```

#### 4. دمج البحث الدلالي في Shopify Hydrogen

يمكنك استدعاء وظيفة `semanticSearch` من الواجهة الخلفية لـ Node.js (عبر API Endpoint) من مكونات Hydrogen الخاصة بك.

**مثال لـ API Endpoint في Node.js (باستخدام Express أو Fastify):**

```javascript
// api/search.js (مثال باستخدام Express)
import express from 'express';
import { semanticSearch, buildSemanticIndex } from '../indexProducts.js';

const app = express();
app.use(express.json());

// بناء الفهرس عند بدء تشغيل الخادم
buildSemanticIndex();

app.post('/semantic-search', async (req, res) => {
    const { query } = req.body;
    if (!query) {
        return res.status(400).json({ error: 'Query is required' });
    }
    try {
        const results = await semanticSearch(query);
        res.json(results);
    } catch (error) {
        res.status(500).json({ error: 'Failed to perform semantic search' });
    }
});

app.listen(3001, () => console.log('Semantic Search API running on port 3001'));
```

**مثال لاستدعاء API من مكون Hydrogen (React):**

```jsx
// components/SemanticSearch.jsx (مثال في Hydrogen)
import React, { useState } from 'react';

export function SemanticSearch() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  const handleSearch = async () => {
    try {
      const response = await fetch('http://localhost:3001/semantic-search', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ query }),
      });
      const data = await response.json();
      setResults(data);
    } catch (error) {
      console.error('Error fetching semantic search results:', error);
    }
  };

  return (
    <div>
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="ابحث بالمعنى..."
      />
      <button onClick={handleSearch}>بحث دلالي</button>
      <div>
        {results.map((product) => (
          <div key={product.id}>
            <h3>{product.title}</h3>
            <p>التشابه: {(product.similarity * 100).toFixed(2)}%</p>
          </div>
        ))}
      </div>
    </div>
  );
}
```

### الخلاصة

يوفر هذا الدليل إطارًا عمليًا لبناء محرك بحث دلالي قوي باستخدام Node.js ودمجه مع Shopify Hydrogen. من خلال الاستفادة من قوة نماذج Embeddings من Hugging Face، يمكن للمتاجر الإلكترونية تقديم تجربة بحث أكثر ذكاءً وتخصيصًا، مما يعزز رضا العملاء ويزيد المبيعات.

### المراجع

[1] Hugging Face Inference API. [https://huggingface.co/docs/api-inference/index](https://huggingface.co/docs/api-inference/index)
[2] Shopify Hydrogen. [https://shopify.dev/custom-storefronts/hydrogen](https://shopify.dev/custom-storefronts/hydrogen)
[3] `sentence-transformers/all-MiniLM-L6-v2` model. [https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2)

---

## دليل عملي: تكامل نماذج اللغة الضخمة (LLMs) مع Node.js و Shopify Hydrogen

### المقدمة

تُعد نماذج اللغة الضخمة (LLMs) مثل GPT-OSS-120B أدوات قوية لتوليد المحتوى، والإجابة على الأسئلة، وتحسين تجربة المستخدم. يوضح هذا الدليل كيفية دمج هذه النماذج مع تطبيقات Node.js، وخصوصًا في سياق متاجر Shopify Hydrogen، لإنشاء تجارب تسوق أكثر ذكاءً وتخصيصًا.

### المكونات الأساسية

1.  **نموذج اللغة الضخم (LLM):** مثل `openai/gpt-oss-120b` أو أي نموذج آخر متاح عبر API.
2.  **Node.js Backend:** للتعامل مع استدعاءات API للنموذج، ومعالجة البيانات، وتوفير واجهات برمجة تطبيقات (APIs) للواجهة الأمامية.
3.  **Shopify Hydrogen Frontend:** لدمج الميزات التي تعمل بالذكاء الاصطناعي في واجهة المستخدم، مثل أوصاف المنتجات التلقائية، أو روبوتات الدردشة، أو توصيات المنتجات.

### الخطوات التنفيذية

#### 1. الوصول إلى نموذج LLM

معظم نماذج LLM الضخمة يتم الوصول إليها عبر واجهات برمجة تطبيقات (APIs). سنفترض استخدام Hugging Face Inference API أو OpenAI API.

```javascript
// llmService.js
import axios from 'axios';

const HF_INFERENCE_API_URL = "https://api-inference.huggingface.co/models/openai/gpt-oss-120b";
const HF_TOKEN = process.env.HF_TOKEN; // أو OPENAI_API_KEY

async function generateText(prompt, maxTokens = 100) {
    try {
        const response = await axios.post(
            HF_INFERENCE_API_URL,
            { inputs: prompt, parameters: { max_new_tokens: maxTokens } },
            {
                headers: {
                    Authorization: `Bearer ${HF_TOKEN}`,
                },
            }
        );
        return response.data[0].generated_text;
    } catch (error) {
        console.error("Error generating text:", error.response ? error.response.data : error.message);
        throw error;
    }
}

export { generateText };
```

#### 2. بناء واجهة خلفية (Backend) في Node.js

يمكنك إنشاء نقطة نهاية (API Endpoint) في Node.js تستدعي خدمة LLM وتوفر المحتوى المولّد للواجهة الأمامية.

```javascript
// api/llm.js (مثال باستخدام Express)
import express from 'express';
import { generateText } from '../llmService.js';

const app = express();
app.use(express.json());

app.post('/generate-product-description', async (req, res) => {
    const { productName, keywords } = req.body;
    if (!productName) {
        return res.status(400).json({ error: 'Product name is required' });
    }
    const prompt = `اكتب وصفًا جذابًا للمنتج التالي: ${productName}. الكلمات المفتاحية: ${keywords || ''}.`;
    try {
        const description = await generateText(prompt, 150);
        res.json({ description });
    } catch (error) {
        res.status(500).json({ error: 'Failed to generate description' });
    }
});

app.listen(3002, () => console.log('LLM Integration API running on port 3002'));
```

#### 3. دمج LLM في Shopify Hydrogen

يمكن لمكونات Hydrogen استدعاء نقطة النهاية الخلفية (Backend Endpoint) لتوليد المحتوى ديناميكيًا.

```jsx
// components/ProductDescriptionGenerator.jsx (مثال في Hydrogen)
import React, { useState } from 'react';

export function ProductDescriptionGenerator({ productId, initialDescription }) {
  const [description, setDescription] = useState(initialDescription);
  const [loading, setLoading] = useState(false);
  const [productName, setProductName] = useState('');
  const [keywords, setKeywords] = useState('');

  const handleGenerateDescription = async () => {
    setLoading(true);
    try {
      const response = await fetch('http://localhost:3002/generate-product-description', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ productName, keywords }),
      });
      const data = await response.json();
      setDescription(data.description);
    } catch (error) {
      console.error('Error generating product description:', error);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <h2>توليد وصف المنتج بالذكاء الاصطناعي</h2>
      <input
        type="text"
        value={productName}
        onChange={(e) => setProductName(e.target.value)}
        placeholder="اسم المنتج"
      />
      <input
        type="text"
        value={keywords}
        onChange={(e) => setKeywords(e.target.value)}
        placeholder="كلمات مفتاحية (اختياري)"
      />
      <button onClick={handleGenerateDescription} disabled={loading}>
        {loading ? 'جاري التوليد...' : 'توليد الوصف'}
      </button>
      {description && (
        <div>
          <h3>الوصف المولّد:</h3>
          <p>{description}</p>
        </div>
      )}
    </div>
  );
}
```

### الخلاصة

من خلال دمج نماذج اللغة الضخمة مع Node.js و Shopify Hydrogen، يمكن للمتاجر الإلكترونية تقديم تجارب مخصصة وديناميكية للعملاء، بدءًا من توليد أوصاف المنتجات وحتى توفير مساعدين افتراضيين. هذا يفتح آفاقًا جديدة للابتكار في التجارة الإلكترونية.

### المراجع

[1] Hugging Face Inference API. [https://huggingface.co/docs/api-inference/index](https://huggingface.co/docs/api-inference/index)
[2] Shopify Hydrogen. [https://shopify.dev/custom-storefronts/hydrogen](https://shopify.dev/custom-storefronts/hydrogen)
[3] `openai/gpt-oss-120b` model. [https://huggingface.co/openai/gpt-oss-120b](https://huggingface.co/openai/gpt-oss-120b)


---

## تطبيق تجريبي: توليد أوصاف المنتجات باستخدام GPT-OSS-120B

لإظهار قوة نموذج `gpt-oss-120b` بشكل عملي، قمنا بإضافة تطبيق تجريبي (`demo-gpt-oss.js`) إلى هذا المستودع. يوضح هذا الكود كيفية استدعاء النموذج عبر Node.js لتوليد أوصاف منتجات جذابة ومفصلة لمتاجر Shopify Hydrogen.

### كيفية الاستخدام

1.  **تثبيت الاعتماديات:**
    ```bash
    npm install axios
    ```
2.  **إعداد مفتاح الوصول:**
    تأكد من تعيين مفتاح الوصول الخاص بك على Hugging Face كمتغير بيئة:
    ```bash
    export HF_TOKEN="hf_..."
    ```
3.  **تشغيل التطبيق التجريبي:**
    ```bash
    node demo-gpt-oss.js
    ```

سيقوم الكود بتوليد وصف لمنتج "فستان سهرة حريري فاخر" باستخدام النموذج، ويمكنك تعديل الكود لتجربة منتجات وكلمات مفتاحية مختلفة.

### الكود المصدري

يمكنك الاطلاع على الكود الكامل في ملف `demo-gpt-oss.js` في هذا المستودع.