جلسه ۴: ساخت برنامه‌های چت تولیدی با Chainlit

مرور کلی

این جلسه بر ساخت برنامه‌های چت آماده تولید با استفاده از Chainlit و Microsoft Foundry Local تمرکز دارد. شما یاد خواهید گرفت که رابط‌های وب مدرن برای مکالمات هوش مصنوعی ایجاد کنید، پاسخ‌های استریم را پیاده‌سازی کنید و برنامه‌های چت قدرتمند با مدیریت خطا و طراحی تجربه کاربری مناسب را مستقر کنید.

آنچه خواهید ساخت:

• برنامه چت Chainlit: رابط کاربری وب مدرن با پاسخ‌های استریم
• دموی WebGPU: استنتاج مبتنی بر مرورگر برای برنامه‌های اولویت‌دار حریم خصوصی
• ادغام Open WebUI: رابط چت حرفه‌ای با Foundry Local
• الگوهای تولیدی: مدیریت خطا، نظارت و استراتژی‌های استقرار

اهداف یادگیری

• ساخت برنامه‌های چت آماده تولید با Chainlit
• پیاده‌سازی پاسخ‌های استریم برای تجربه کاربری بهتر
• تسلط بر الگوهای ادغام SDK Foundry Local
• اعمال مدیریت خطا و کاهش تدریجی مناسب
• استقرار و پیکربندی برنامه‌های چت برای محیط‌های مختلف
• درک الگوهای رابط کاربری وب مدرن برای هوش مصنوعی مکالمه‌ای

پیش‌نیازها

• Foundry Local: نصب و اجرا شده (راهنمای نصب)
• Python: نسخه ۳.۱۰ یا بالاتر با قابلیت محیط مجازی
• مدل: حداقل یک مدل بارگذاری شده (foundry model run phi-4-mini)
• مرورگر: مرورگر وب مدرن با پشتیبانی WebGPU (Chrome/Edge)
• Docker: برای ادغام Open WebUI (اختیاری)

بخش ۱: درک برنامه‌های چت مدرن

مرور معماری

User Browser ←→ Chainlit UI ←→ Python Backend ←→ Foundry Local ←→ AI Model
      ↓              ↓              ↓              ↓            ↓
   Web UI      Event Handlers   OpenAI Client   HTTP API    Local GPU

فناوری‌های کلیدی

الگوهای SDK Foundry Local:

• FoundryLocalManager(alias): مدیریت خودکار سرویس
• manager.endpoint و manager.api_key: جزئیات اتصال
• manager.get_model_info(alias).id: شناسایی مدل

چارچوب Chainlit:

• @cl.on_chat_start: شروع جلسات چت
• @cl.on_message: مدیریت پیام‌های ورودی کاربران
• cl.Message().stream_token(): استریم در زمان واقعی
• تولید خودکار رابط کاربری و مدیریت WebSocket

بخش ۲: ماتریس تصمیم‌گیری محلی در مقابل ابری

ویژگی‌های عملکردی

جنبه	محلی (Foundry)	ابری (Azure OpenAI)
تاخیر	🚀 ۵۰-۲۰۰ میلی‌ثانیه (بدون شبکه)	⏱️ ۲۰۰-۲۰۰۰ میلی‌ثانیه (وابسته به شبکه)
حریم خصوصی	🔒 داده‌ها هرگز دستگاه را ترک نمی‌کنند	⚠️ داده‌ها به ابر ارسال می‌شوند
هزینه	💰 رایگان پس از سخت‌افزار	💸 پرداخت به ازای هر توکن
آفلاین	✅ کار بدون اینترنت	❌ نیاز به اینترنت
اندازه مدل	⚠️ محدود به سخت‌افزار	✅ دسترسی به بزرگ‌ترین مدل‌ها
مقیاس‌پذیری	⚠️ وابسته به سخت‌افزار	✅ مقیاس‌پذیری نامحدود

الگوهای استراتژی ترکیبی

اولویت محلی با پشتیبان:

async def hybrid_completion(prompt: str, complexity_threshold: int = 100):
    if len(prompt.split()) < complexity_threshold:
        return await local_completion(prompt)  # Fast, private
    else:
        return await cloud_completion(prompt)   # Complex reasoning

مسیر‌یابی مبتنی بر وظیفه:

async def smart_routing(prompt: str, task_type: str):
    routing_rules = {
        "code_generation": "local",     # Privacy-sensitive
        "creative_writing": "cloud",    # Benefits from larger models
        "data_analysis": "local",       # Fast iteration needed
        "research": "cloud"             # Requires broad knowledge
    }
    
    if routing_rules.get(task_type) == "local":
        return await foundry_completion(prompt)
    else:
        return await azure_completion(prompt)

بخش ۳: نمونه ۰۴ - برنامه چت Chainlit

شروع سریع

# Navigate to Module08 directory  
cd Module08

# Start your preferred model
foundry model run phi-4-mini

# Run the Chainlit application (avoiding port conflicts)
chainlit run samples\04\app.py -w --port 8080

برنامه به طور خودکار در http://localhost:8080 با یک رابط چت مدرن باز می‌شود.

پیاده‌سازی اصلی

برنامه نمونه ۰۴ الگوهای آماده تولید را نشان می‌دهد:

کشف خودکار سرویس:

import chainlit as cl
from openai import OpenAI
from foundry_local import FoundryLocalManager

# Global variables for client and model
client = None
model_name = None

async def initialize_client():
    global client, model_name
    alias = os.environ.get("MODEL", "phi-4-mini")
    
    try:
        # Use FoundryLocalManager for proper service management
        manager = FoundryLocalManager(alias)
        model_info = manager.get_model_info(alias)
        
        client = OpenAI(
            base_url=manager.endpoint,
            api_key=manager.api_key or "not-required"
        )
        model_name = model_info.id if model_info else alias
        return True
    except Exception as e:
        # Fallback to manual configuration
        base_url = os.environ.get("BASE_URL", "http://localhost:51211")
        client = OpenAI(base_url=f"{base_url}/v1", api_key="not-required")
        model_name = alias
        return True

مدیریت چت استریم:

@cl.on_message
async def main(message: cl.Message):
    # Create streaming response
    msg = cl.Message(content="")
    await msg.send()
    
    stream = client.chat.completions.create(
        model=model_name,
        messages=[
            {"role": "system", "content": "You are a helpful AI assistant."},
            {"role": "user", "content": message.content}
        ],
        stream=True
    )
    
    # Stream tokens in real-time
    for chunk in stream:
        if chunk.choices[0].delta.content:
            await msg.stream_token(chunk.choices[0].delta.content)
    
    await msg.update()

گزینه‌های پیکربندی

متغیرهای محیطی:

متغیر	توضیحات	پیش‌فرض	مثال
MODEL	نام مستعار مدل مورد استفاده	phi-4-mini	qwen2.5-7b
BASE_URL	نقطه پایانی Foundry Local	به صورت خودکار شناسایی شده	http://localhost:51211
API_KEY	کلید API (اختیاری برای محلی)	""	your-api-key

استفاده پیشرفته:

# Use different model
set MODEL=qwen2.5-7b
chainlit run samples\04\app.py -w --port 8080

# Use different ports (avoid 51211 which is used by Foundry Local)
chainlit run samples\04\app.py -w --port 3000
chainlit run samples\04\app.py -w --port 5000

بخش ۴: ایجاد و استفاده از نوت‌بوک‌های Jupyter

مرور کلی پشتیبانی نوت‌بوک

نمونه ۰۴ شامل یک نوت‌بوک جامع Jupyter (chainlit_app.ipynb) است که ارائه می‌دهد:

• 📚 محتوای آموزشی: مواد یادگیری گام به گام
• 🔬 کاوش تعاملی: اجرای و آزمایش سلول‌های کد
• 📊 نمایش‌های بصری: نمودارها، دیاگرام‌ها و تجسم خروجی
• 🛠️ ابزارهای توسعه: قابلیت‌های تست و اشکال‌زدایی

ایجاد نوت‌بوک‌های خودتان

مرحله ۱: تنظیم محیط Jupyter

# Ensure you're in the Module08 directory
cd Module08

# Activate your virtual environment
.venv\Scripts\activate

# Install Jupyter and dependencies
pip install jupyter notebook jupyterlab ipykernel
pip install -r requirements.txt

# Register the kernel for VS Code
python -m ipykernel install --user --name=foundry-local --display-name="Foundry Local"

مرحله ۲: ایجاد یک نوت‌بوک جدید

با استفاده از VS Code:

1. VS Code را در دایرکتوری Module08 باز کنید
2. یک فایل جدید با پسوند .ipynb ایجاد کنید
3. هنگام درخواست، هسته "Foundry Local" را انتخاب کنید
4. شروع به افزودن سلول‌ها با محتوای خود کنید

با استفاده از Jupyter Lab:

# Start Jupyter Lab
jupyter lab

# Navigate to samples/04/ and create new notebook
# Choose Python 3 kernel

بهترین شیوه‌های ساختار نوت‌بوک

سازماندهی سلول‌ها

# Cell 1: Imports and Setup
import os
import sys
import chainlit as cl
from openai import OpenAI
from foundry_local import FoundryLocalManager

print("✅ Libraries imported successfully")

# Cell 2: Configuration and Client Setup
class FoundryClientManager:
    def __init__(self, model_name="phi-4-mini"):
        self.model_name = model_name
        self.client = None
        
    def initialize_client(self):
        # Client initialization logic
        pass

# Initialize and test
client_manager = FoundryClientManager()
result = client_manager.initialize_client()
print(f"Client initialized: {result}")

مثال‌ها و تمرین‌های تعاملی

تمرین ۱: تست پیکربندی کلاینت

# Test different configuration methods
configurations = [
    {"method": "foundry_sdk", "model": "phi-4-mini"},
    {"method": "manual", "base_url": "http://localhost:51211", "model": "qwen2.5-7b"},
]

for config in configurations:
    print(f"\n🧪 Testing {config['method']} configuration...")
    # Implementation here
    result = test_configuration(config)
    print(f"Result: {'✅ Success' if result['status'] == 'ok' else '❌ Failed'}")

تمرین ۲: شبیه‌سازی پاسخ استریم

import asyncio

async def simulate_streaming_response(text, delay=0.1):
    """Simulate how streaming works in Chainlit."""
    print("🌊 Simulating streaming response...")
    
    for char in text:
        print(char, end='', flush=True)
        await asyncio.sleep(delay)
    
    print("\n✅ Streaming complete!")

# Test the simulation
sample_text = "This is how streaming responses work in Chainlit applications!"
await simulate_streaming_response(sample_text)

بخش ۵: دموی استنتاج مرورگر WebGPU

مرور کلی

WebGPU امکان اجرای مدل‌های هوش مصنوعی را مستقیماً در مرورگر برای حداکثر حریم خصوصی و تجربه‌های بدون نصب فراهم می‌کند. این نمونه اجرای ONNX Runtime Web با WebGPU را نشان می‌دهد.

مرحله ۱: بررسی پشتیبانی WebGPU

نیازمندی‌های مرورگر:

• Chrome/Edge نسخه ۱۱۳+ با WebGPU فعال
• بررسی: chrome://gpu → تأیید وضعیت "WebGPU"
• بررسی برنامه‌نویسی: if (!('gpu' in navigator)) { /* no WebGPU */ }

مرحله ۲: ایجاد دموی WebGPU

ایجاد دایرکتوری: samples/04/webgpu-demo/

index.html:

<!doctype html>
<html>
<head>
    <meta charset="utf-8">
    <title>WebGPU + ONNX Runtime Demo</title>
    <script src="https://cdn.jsdelivr.net/npm/onnxruntime-web/dist/ort.webgpu.min.js"></script>
    <style>
        body { font-family: system-ui, sans-serif; margin: 2rem; }
        pre { background: #f5f5f5; padding: 1rem; overflow: auto; }
        .status { padding: 1rem; background: #e3f2fd; border-radius: 4px; }
    </style>
</head>
<body>
    <h1>🚀 WebGPU + Foundry Local Integration</h1>
    <div id="status" class="status">Initializing...</div>
    <pre id="output"></pre>
    <script type="module" src="./main.js"></script>
</body>
</html>

main.js:

const statusEl = document.getElementById('status');
const outputEl = document.getElementById('output');

function log(msg) {
    outputEl.textContent += `${msg}\n`;
    console.log(msg);
}

(async () => {
    try {
        if (!('gpu' in navigator)) {
            statusEl.textContent = '❌ WebGPU not available';
            return;
        }
        
        statusEl.textContent = '🔍 WebGPU detected. Loading model...';
        
        // Use a small ONNX model for demo
        const modelUrl = 'https://huggingface.co/onnx/models/resolve/main/vision/classification/mnist-12/mnist-12.onnx';
        
        const session = await ort.InferenceSession.create(modelUrl, {
            executionProviders: ['webgpu']
        });
        
        log('✅ ONNX Runtime session created with WebGPU');
        log(`📊 Input names: ${session.inputNames.join(', ')}`);
        log(`📊 Output names: ${session.outputNames.join(', ')}`);
        
        // Create dummy input (MNIST expects 1x1x28x28)
        const inputData = new Float32Array(1 * 1 * 28 * 28).fill(0.1);
        const input = new ort.Tensor('float32', inputData, [1, 1, 28, 28]);
        
        const feeds = {};
        feeds[session.inputNames[0]] = input;
        
        const results = await session.run(feeds);
        const output = results[session.outputNames[0]];
        
        // Find prediction (argmax)
        let maxIdx = 0;
        for (let i = 1; i < output.data.length; i++) {
            if (output.data[i] > output.data[maxIdx]) maxIdx = i;
        }
        
        statusEl.textContent = '✅ WebGPU inference complete!';
        log(`🎯 Predicted class: ${maxIdx}`);
        log(`📈 Confidence scores: [${Array.from(output.data).map(x => x.toFixed(3)).join(', ')}]`);
        
    } catch (error) {
        statusEl.textContent = `❌ Error: ${error.message}`;
        log(`Error: ${error.message}`);
        console.error(error);
    }
})();

مرحله ۳: اجرای دمو

# Create demo directory
mkdir samples\04\webgpu-demo
cd samples\04\webgpu-demo

# Save HTML and JS files, then serve
python -m http.server 5173

# Open browser to http://localhost:5173

بخش ۶: ادغام Open WebUI

مرور کلی

Open WebUI یک رابط حرفه‌ای مشابه ChatGPT ارائه می‌دهد که به API سازگار با OpenAI Foundry Local متصل می‌شود.

مرحله ۱: پیش‌نیازها

# Verify Foundry Local is running
foundry service status

# Start a model
foundry model run phi-4-mini

# Confirm API endpoint is accessible
curl http://localhost:51211/v1/models

مرحله ۲: تنظیم Docker (توصیه شده)

# Pull Open WebUI image
docker pull ghcr.io/open-webui/open-webui:main

# Run with Foundry Local connection
docker run -d --name open-webui -p 3000:8080 ^
  -e OPENAI_API_BASE_URL=http://host.docker.internal:51211/v1 ^
  -e OPENAI_API_KEY=foundry-local-key ^
  -v open-webui-data:/app/backend/data ^
  ghcr.io/open-webui/open-webui:main

توجه: host.docker.internal به کانتینرهای Docker اجازه می‌دهد به ماشین میزبان در ویندوز دسترسی پیدا کنند.

مرحله ۳: پیکربندی

1. باز کردن مرورگر: به http://localhost:3000 بروید
2. تنظیم اولیه: ایجاد حساب کاربری مدیر
3. پیکربندی مدل:
   • تنظیمات → مدل‌ها → API OpenAI
   • آدرس پایه: http://host.docker.internal:51211/v1
   • کلید API: foundry-local-key (هر مقداری کار می‌کند)
4. تست اتصال: مدل‌ها باید در منوی کشویی ظاهر شوند

رفع اشکال

مشکلات رایج:

1. اتصال رد شد:

   # Check Foundry Local status
   foundry service ps
   netstat -ano | findstr :51211
   

2. مدل‌ها ظاهر نمی‌شوند:

   • تأیید کنید که مدل بارگذاری شده است: foundry model list
   • بررسی پاسخ API: curl http://localhost:51211/v1/models
   • راه‌اندازی مجدد کانتینر Open WebUI

بخش ۷: ملاحظات استقرار تولیدی

پیکربندی محیط

تنظیمات توسعه:

# Development with auto-reload and debugging
chainlit run samples\04\app.py -w --port 8080 --debug

استقرار تولیدی:

# Production mode with optimizations
chainlit run samples\04\app.py --host 0.0.0.0 --port 8080 --no-cache

مشکلات رایج پورت و راه‌حل‌ها

پیشگیری از تعارض پورت ۵۱۲۱۱:

# Check what's using Foundry Local port
netstat -ano | findstr :51211

# Use different port for Chainlit
chainlit run samples\04\app.py -w --port 8080

نظارت بر عملکرد

پیاده‌سازی بررسی سلامت:

@cl.on_chat_start
async def health_check():
    try:
        # Test model availability
        response = client.chat.completions.create(
            model=model_name,
            messages=[{"role": "user", "content": "test"}],
            max_tokens=1
        )
        return {"status": "healthy", "model": model_name}
    except Exception as e:
        return {"status": "unhealthy", "error": str(e)}

خلاصه

جلسه ۴ به ساخت برنامه‌های Chainlit آماده تولید برای هوش مصنوعی مکالمه‌ای پرداخت. شما درباره موارد زیر یاد گرفتید:

• ✅ چارچوب Chainlit: رابط کاربری مدرن و پشتیبانی استریم برای برنامه‌های چت
• ✅ ادغام Foundry Local: استفاده از SDK و الگوهای پیکربندی
• ✅ استنتاج WebGPU: هوش مصنوعی مبتنی بر مرورگر برای حداکثر حریم خصوصی
• ✅ تنظیم Open WebUI: استقرار رابط چت حرفه‌ای
• ✅ الگوهای تولیدی: مدیریت خطا، نظارت و مقیاس‌پذیری

برنامه نمونه ۰۴ بهترین شیوه‌ها را برای ساخت رابط‌های چت قدرتمند که از مدل‌های هوش مصنوعی محلی از طریق Microsoft Foundry Local استفاده می‌کنند و تجربه‌های کاربری عالی ارائه می‌دهند، نشان می‌دهد.

منابع

• نمونه ۰۴: برنامه Chainlit: برنامه کامل با مستندات
• نوت‌بوک آموزشی Chainlit: مواد یادگیری تعاملی
• مستندات Foundry Local: مستندات کامل پلتفرم
• مستندات Chainlit: مستندات رسمی چارچوب
• راهنمای ادغام Open WebUI: آموزش رسمی

---

سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما تلاش می‌کنیم دقت را حفظ کنیم، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌ها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، توصیه می‌شود از ترجمه انسانی حرفه‌ای استفاده کنید. ما مسئولیتی در قبال سوء تفاهم‌ها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.