بناء خط أنابيب RAG عربي مع تطبيع النصوص في TypeScript

npx create-next-app@latest arabic-rag --typescript --app --src-dir --turbopack
cd arabic-rag

npm install @lancedb/lancedb openai @anthropic-ai/sdk
npm install -D tsx

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

const TASHKEEL = /[ؐ-ًؚ-ٰٟ]/g;
const TATWEEL = /ـ/g;
const ALEF_VARIANTS = /[آأإٱ]/g;
const HAMZA_ON_WAW = /ؤ/g;
const HAMZA_ON_YA = /ئ/g;
const TEH_MARBUTA = /ة/g;
const ALEF_MAQSURAH = /ى/g;
const EXTRA_SPACES = /\s+/g;
 
export interface NormalizerOptions {
  removeTashkeel?: boolean;
  removeTatweel?: boolean;
  normalizeAlef?: boolean;
  normalizeHamza?: boolean;
  normalizeTehMarbuta?: boolean;
  normalizeAlefMaqsurah?: boolean;
}
 
const DEFAULT_OPTIONS: NormalizerOptions = {
  removeTashkeel: true,
  removeTatweel: true,
  normalizeAlef: true,
  normalizeHamza: false,
  normalizeTehMarbuta: false,
  normalizeAlefMaqsurah: true,
};
 
export function normalizeArabic(
  text: string,
  options: NormalizerOptions = DEFAULT_OPTIONS
): string {
  let result = text.normalize("NFKC");
 
  if (options.removeTashkeel) result = result.replace(TASHKEEL, "");
  if (options.removeTatweel) result = result.replace(TATWEEL, "");
  if (options.normalizeAlef) result = result.replace(ALEF_VARIANTS, "ا");
  if (options.normalizeHamza) {
    result = result.replace(HAMZA_ON_WAW, "و");
    result = result.replace(HAMZA_ON_YA, "ي");
  }
  if (options.normalizeTehMarbuta)
    result = result.replace(TEH_MARBUTA, "ه");
  if (options.normalizeAlefMaqsurah)
    result = result.replace(ALEF_MAQSURAH, "ي");
 
  return result.replace(EXTRA_SPACES, " ").trim();
}
 
export const normalizeForIndexing = (text: string) =>
  normalizeArabic(text, DEFAULT_OPTIONS);
 
export const normalizeForQuery = (text: string) =>
  normalizeArabic(text, DEFAULT_OPTIONS);

import OpenAI from "openai";
 
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
export const EMBEDDING_MODEL = "text-embedding-3-small";
export const EMBEDDING_DIMENSIONS = 1536;
 
export async function embedText(text: string): Promise<number[]> {
  const res = await openai.embeddings.create({
    model: EMBEDDING_MODEL,
    input: text,
    encoding_format: "float",
  });
  return res.data[0].embedding;
}
 
export async function embedBatch(texts: string[]): Promise<number[][]> {
  if (texts.length === 0) return [];
  const res = await openai.embeddings.create({
    model: EMBEDDING_MODEL,
    input: texts,
    encoding_format: "float",
  });
  return res.data.map((d) => d.embedding);
}

import * as lancedb from "@lancedb/lancedb";
 
export interface ArabicDocument {
  id: string;
  text: string;
  normalizedText: string;
  vector: number[];
  source: string;
  metadata: string;
}
 
let conn: lancedb.Connection | null = null;
 
async function getConn(): Promise<lancedb.Connection> {
  if (!conn) conn = await lancedb.connect(".lancedb");
  return conn;
}
 
export async function addDocuments(
  docs: ArabicDocument[],
  tableName = "arabic_docs"
): Promise<void> {
  const db = await getConn();
  const tables = await db.tableNames();
 
  if (tables.includes(tableName)) {
    const table = await db.openTable(tableName);
    await table.add(docs);
  } else {
    await db.createTable(tableName, docs);
  }
}
 
export async function searchDocuments(
  queryVector: number[],
  limit = 5,
  tableName = "arabic_docs"
): Promise<ArabicDocument[]> {
  const db = await getConn();
  const table = await db.openTable(tableName);
  return (await table.search(queryVector).limit(limit).toArray()) as ArabicDocument[];
}

import { normalizeForIndexing } from "./arabic-normalizer";
import { embedBatch } from "./embeddings";
import { addDocuments, type ArabicDocument } from "./vector-store";
 
export interface RawDocument {
  text: string;
  source: string;
  metadata?: Record<string, string>;
}
 
function chunkArabicText(text: string, maxChars = 800): string[] {
  // تقسيم على علامات نهاية الجملة الشائعة في النصوص العربية.
  // ملاحظة: علامة الاستفهام العربية ؟ (U+061F) يجب تضمينها مع ?
  const sentences = text
    .split(/[.!?؟\n]+/)
    .map((s) => s.trim())
    .filter((s) => s.length > 20);
 
  const chunks: string[] = [];
  let current = "";
 
  for (const sentence of sentences) {
    const candidate = current ? current + " " + sentence : sentence;
    if (candidate.length > maxChars && current) {
      chunks.push(current);
      current = sentence;
    } else {
      current = candidate;
    }
  }
  if (current) chunks.push(current);
  return chunks;
}
 
export async function indexDocuments(
  rawDocs: RawDocument[],
  batchSize = 20
): Promise<void> {
  type Chunk = {
    text: string;
    normalized: string;
    source: string;
    meta: string;
  };
 
  const allChunks: Chunk[] = [];
 
  for (const doc of rawDocs) {
    const chunks = chunkArabicText(doc.text);
    for (const chunk of chunks) {
      allChunks.push({
        text: chunk,
        normalized: normalizeForIndexing(chunk),
        source: doc.source,
        meta: JSON.stringify(doc.metadata ?? {}),
      });
    }
  }
 
  for (let i = 0; i < allChunks.length; i += batchSize) {
    const batch = allChunks.slice(i, i + batchSize);
    const embeddings = await embedBatch(batch.map((c) => c.normalized));
 
    const docs: ArabicDocument[] = batch.map((chunk, j) => ({
      id: crypto.randomUUID(),
      text: chunk.text,
      normalizedText: chunk.normalized,
      vector: embeddings[j],
      source: chunk.source,
      metadata: chunk.meta,
    }));
 
    await addDocuments(docs);
    process.stderr.write(
      `Indexed ${i + batch.length}/${allChunks.length} chunks\n`
    );
  }
}

import { normalizeForQuery } from "./arabic-normalizer";
import { embedText } from "./embeddings";
import { searchDocuments } from "./vector-store";
 
export interface RetrievalResult {
  text: string;
  source: string;
  rank: number;
}
 
export async function retrieve(
  query: string,
  topK = 5
): Promise<RetrievalResult[]> {
  const normalizedQuery = normalizeForQuery(query);
  const queryVector = await embedText(normalizedQuery);
  const results = await searchDocuments(queryVector, topK);
 
  return results.map((doc, i) => ({
    text: doc.text,
    source: doc.source,
    rank: i + 1,
  }));
}

import Anthropic from "@anthropic-ai/sdk";
import type { RetrievalResult } from "./retriever";
 
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 
type Lang = "ar" | "en" | "fr";
 
const SYSTEM_PROMPTS: Record<Lang, string> = {
  ar: "أنت مساعد متخصص يجيب على الأسئلة بالعربية الفصحى الواضحة. استند فقط إلى السياق المقدم. إذا لم يتضمن السياق الإجابة، فأخبر المستخدم بذلك صراحةً.",
  en: "You are a specialized assistant that answers questions in clear English. Base your answers only on the provided context. If the context does not contain the answer, say so explicitly.",
  fr: "Tu es un assistant spécialisé qui répond en français clair. Base-toi uniquement sur le contexte fourni. Si le contexte ne contient pas la réponse, dis-le explicitement.",
};
 
export async function generateAnswer(
  query: string,
  context: RetrievalResult[],
  lang: Lang = "ar"
): Promise<string> {
  const contextText = context
    .map((r) => `[${r.rank}] ${r.text}\nالمصدر: ${r.source}`)
    .join("\n\n---\n\n");
 
  const userPrompt =
    lang === "ar"
      ? `السياق:\n\n${contextText}\n\nالسؤال: ${query}`
      : `Context:\n\n${contextText}\n\nQuestion: ${query}`;
 
  const response = await anthropic.messages.create({
    model: "claude-sonnet-5",
    max_tokens: 1024,
    system: SYSTEM_PROMPTS[lang],
    messages: [{ role: "user", content: userPrompt }],
  });
 
  const block = response.content[0];
  if (block.type !== "text") throw new Error("Unexpected content block type");
  return block.text;
}

import { NextRequest, NextResponse } from "next/server";
import { retrieve } from "@/lib/retriever";
import { generateAnswer } from "@/lib/generator";
 
export const runtime = "nodejs";
export const maxDuration = 30;
 
export async function POST(req: NextRequest) {
  try {
    const { query, lang = "ar", topK = 5 } = (await req.json()) as {
      query: string;
      lang?: "ar" | "en" | "fr";
      topK?: number;
    };
 
    if (!query || typeof query !== "string") {
      return NextResponse.json({ error: "query is required" }, { status: 400 });
    }
 
    const context = await retrieve(query, topK);
 
    if (context.length === 0) {
      return NextResponse.json(
        {
          answer:
            lang === "ar"
              ? "لم أجد معلومات كافية للإجابة على سؤالك."
              : "No relevant documents found.",
          context: [],
        },
        { status: 200 }
      );
    }
 
    const answer = await generateAnswer(query, context, lang);
    return NextResponse.json({ answer, context });
  } catch (err) {
    console.error("[arabic-rag]", err);
    return NextResponse.json(
      { error: "Internal server error" },
      { status: 500 }
    );
  }
}

import { indexDocuments } from "../src/lib/indexer";
 
const sampleDocs = [
  {
    text: "الذكاء الاصطناعي هو محاكاة للذكاء البشري في الآلات التي تم برمجتها للتفكير مثل البشر وتقليد أفعالهم. يشمل هذا المصطلح أي آلة تُظهر سمات مرتبطة بالعقل البشري مثل التعلم وحل المشكلات.",
    source: "مقدمة إلى الذكاء الاصطناعي",
    metadata: { category: "تقنية" },
  },
  {
    text: "التعلم الآلي هو تطبيق للذكاء الاصطناعي يوفر للأنظمة القدرة على التعلم التلقائي والتحسن من الخبرة دون أن تتم برمجتها صراحةً. يركز على تطوير برامج الكمبيوتر التي يمكنها الوصول إلى البيانات واستخدامها للتعلم الذاتي.",
    source: "أساسيات التعلم الآلي",
    metadata: { category: "تقنية" },
  },
  {
    text: "معالجة اللغات الطبيعية هي فرع من فروع الذكاء الاصطناعي يتعلق بالتفاعل بين أجهزة الكمبيوتر والبشر باستخدام اللغة الطبيعية. الهدف النهائي هو قراءة النصوص وفهمها والاستجابة لها بطريقة ذات معنى.",
    source: "معالجة اللغات الطبيعية",
    metadata: { category: "تقنية" },
  },
];
 
indexDocuments(sampleDocs)
  .then(() => {
    process.stderr.write("Seeding complete\n");
    process.exit(0);
  })
  .catch((err) => {
    console.error(err);
    process.exit(1);
  });

npx tsx scripts/seed.ts
npm run dev

curl -X POST http://localhost:3000/api/arabic-rag \
  -H "Content-Type: application/json" \
  -d '{"query":"ما هو التعلم الآلي؟","lang":"ar"}'