Executive Verdict & Key Takeaways
ابنِ مساعداً طرفياً بلغة Python مع موفرَي نماذج صريحين، وجلسات محادثة في SQLite، وسجل محدود، وإعادات محاولة مضبوطة، واختبارات.
ما الذي ستبنيه
يبني هذا الدرس التقني تطبيق محادثة محلياً بلغة Python يتيح للمستخدم الاختيار بين نموذج بأسلوب OpenAI ChatGPT وAnthropic Claude Sonnet ٥. يستخدم التطبيق تنسيق رسائل داخلياً واحداً، ويخزن الجلسات في SQLite، ولا يحتفظ إلا بعدد محدود من الرسائل الحديثة في كل طلب، ويجعل اختيار الموفر ظاهراً في الطرفية.
التوقيت مهم. فقد قدمت Anthropic نموذج Claude Sonnet ٥ في ٣٠ يونيو ٢٠٢٦ بوصفه أكثر نماذج Sonnet لديها قدرةً على العمل كوكيل. وتقول Anthropic إن النموذج يستطيع وضع الخطط، واستخدام أدوات مثل المتصفحات والطرفيات، والعمل باستقلالية بمستوى قدرات كان يتطلب حديثاً نماذج أكبر وأكثر كلفة. كما تضع Sonnet ٥ قريباً من أداء Opus ٤.٨ بأسعار أقل، مع تحسينات مقارنة بـ Sonnet ٤.٦ في الاستدلال، واستخدام الأدوات، والبرمجة، والعمل المعرفي.
لكن ذلك لا يعني أن على عميل محادثة محلي منح النموذج تلقائياً صلاحية الوصول إلى متصفح أو طرفية أو نظام عملاء أو قاعدة بيانات داخلية. ينفذ هذا الدرس التقني محادثة نصية فقط عن قصد. فهو ينشئ أولاً حدوداً موثوقة لمقارنة النماذج وسير عمل المحادثة. وإذا أضفت أدوات لاحقاً، فيجب أن يتحقق كود التطبيق الحتمي من الصلاحيات والوسائط والمهل الزمنية ومتطلبات الموافقة قبل تنفيذ أي إجراء خارجي.
يفيد هذا النهج فرق الهندسة في دول الخليج والشرق الأوسط التي تحتاج إلى تقييم أكثر من موفر واحد للذكاء الاصطناعي مع الاحتفاظ بالتحكم في معمارية تطبيقاتها. لا يرسل التطبيق بصمت طلب Claude فاشلاً إلى OpenAI أو العكس. يختار المستخدم الموفر، ما يجعل سلوك التوجيه واضحاً أثناء التقييم التقني ومراجعة الحوكمة.
المعمارية
config.pyيقرأ متغيرات البيئة المطلوبة ويتحقق من الحدود المحلية الآمنة.providers.pyيحول تنسيق محادثة داخلياً واحداً إلى تنسيق طلب كل موفر.storage.pyينشئ جلسات SQLite دائمة ويسترجع السجل الحديث بترتيب زمني.chat.pyيوفر حلقة الطرفية والأوامر وإعادات المحاولة المضبوطة وتوجيه الموفر.
مهايئ الموفر هو قرار التصميم المهم. تعتمد بقية أجزاء البرنامج على عقد داخلي صغير بدلاً من الاعتماد مباشرة على SDK خاص بمورد معين. وهذا يجعل اختبار التطبيق أسهل، ويتيح لك إضافة بوابة داخلية معتمدة لاحقاً دون إعادة كتابة طبقة التخزين أو معالجة الأوامر.
المتطلبات الأساسية والإعداد
هل تبني تطبيقات أعمال أو تدفقات ذكاء اصطناعي من الصفر؟
تجاوز بناء الهياكل البرمجية التقليدية وإعداد CRUD. ولّد نظام Micro-ERP يعمل بـ PostgreSQL في دقائق.
- Python ٣.١٠ أو أحدث.
- مفتاح OpenAI API ومعرف نموذج متاح لحسابك.
- مفتاح Anthropic API وصلاحية الوصول إلى Claude Sonnet ٥.
- معرفة أساسية بالبيئات الافتراضية ومتغيرات البيئة والطرفية.
- SQLite، وهي مضمنة مع تثبيتات CPython القياسية.
mkdir multi-model-chat
cd multi-model-chat
python -m venv .venv
# macOS and Linux
source .venv/bin/activate
# Windows PowerShell
# ..venvScriptsActivate.ps1
python -m pip install --upgrade pip
python -m pip install openai anthropic rich pytest
mkdir testsلا تضع بيانات الاعتماد في ملفات مصدر Python. اضبطها في بيئة الصدفة لديك، أو مخزن أسرار CI، أو بيئة تشغيل الحاوية، أو مدير الأسرار المعتمد للنشر. يتطلب التطبيق اسم نموذج مُعداً لكل موفر لأن توافر النماذج يعتمد على الحساب.
# macOS and Linux
export OPENAI_API_KEY="your-openai-key"
export OPENAI_MODEL="your-openai-model"
export ANTHROPIC_API_KEY="your-anthropic-key"
export ANTHROPIC_MODEL="claude-sonnet-5"
# Optional local limits
export MAX_HISTORY_MESSAGES="20"
export MAX_OUTPUT_TOKENS="1200"
export REQUEST_TIMEOUT_SECONDS="60"في Windows PowerShell، استخدم صيغة $env:OPENAI_API_KEY="..." بدلاً من ذلك. وفي بيئة إنتاج، مرر أسماء المتغيرات نفسها عبر آلية الأسرار المُدارة في المنصة. لا تطبع المفاتيح في السجلات مطلقاً، ولا تدرجها في Git، ولا تشحنها إلى كود المتصفح.
الخطوة ١: أضف التحقق من الإعدادات
أنشئ config.py. تحافظ هذه الوحدة الصغيرة على فصل الإعدادات عن منطق الأعمال، وتفشل مبكراً عندما يكون أي حد غير صالح. ولا تتطلب اعتماد dotenv؛ إذ إن متغيرات البيئة هي مدخلاتها الوحيدة.
from __future__ import annotations
import os
from dataclasses import dataclass
from pathlib import Path
@dataclass(frozen=True)
class Settings:
openai_api_key: str | None
openai_model: str | None
anthropic_api_key: str | None
anthropic_model: str | None
max_history_messages: int
max_output_tokens: int
request_timeout_seconds: float
database_path: Path
def require_openai(self) -> tuple[str, str]:
if not self.openai_api_key or not self.openai_model:
raise RuntimeError(
"OPENAI_API_KEY and OPENAI_MODEL are required for OpenAI."
)
return self.openai_api_key, self.openai_model
def require_anthropic(self) -> tuple[str, str]:
if not self.anthropic_api_key or not self.anthropic_model:
raise RuntimeError(
"ANTHROPIC_API_KEY and ANTHROPIC_MODEL are required for Anthropic."
)
return self.anthropic_api_key, self.anthropic_model
def read_positive_int(name: str, default: int, minimum: int) -> int:
value = int(os.getenv(name, str(default)))
if value < minimum:
raise ValueError(f"{name} must be at least {minimum}.")
return value
def get_settings() -> Settings:
timeout = float(os.getenv("REQUEST_TIMEOUT_SECONDS", "60"))
if timeout <= 0:
raise ValueError("REQUEST_TIMEOUT_SECONDS must be greater than zero.")
return Settings(
openai_api_key=os.getenv("OPENAI_API_KEY"),
openai_model=os.getenv("OPENAI_MODEL"),
anthropic_api_key=os.getenv("ANTHROPIC_API_KEY"),
anthropic_model=os.getenv("ANTHROPIC_MODEL"),
max_history_messages=read_positive_int(
"MAX_HISTORY_MESSAGES", default=20, minimum=2
),
max_output_tokens=read_positive_int(
"MAX_OUTPUT_TOKENS", default=1200, minimum=1
),
request_timeout_seconds=timeout,
database_path=Path(os.getenv("SQLITE_DATABASE_PATH", "chat_history.sqlite3")),
)حد عدد الرسائل هو إجراء وقائي بسيط، وليس عداداً للرموز. إذ يمكن للنماذج المختلفة ترميز النص نفسه بطرق مختلفة، ولا يمثل عدد أحرف قصير بديلاً موثوقاً لحجم الطلب. إن إبقاء قاعدة الاقتطاع معزولة يعني أنه يمكنك استبدالها لاحقاً بميزانية رموز تراعي الموفر أو بالتلخيص.
الخطوة ٢: أنشئ طبقة مهايئ الموفر
أنشئ providers.py. تستخدم OpenAI وAnthropic أشكالاً مختلفة للطلبات والاستجابات. يحول المهايئ الاستجابتين إلى CompletionResult، ولذلك لا تحتاج CLI إلى كود تحليل خاص بكل موفر.
from __future__ import annotations
from dataclasses import dataclass
from typing import Literal, Protocol, Sequence
from anthropic import Anthropic
from openai import OpenAI
from config import Settings
Role = Literal["user", "assistant"]
ProviderName = Literal["openai", "anthropic"]
@dataclass(frozen=True)
class ChatMessage:
role: Role
content: str
@dataclass(frozen=True)
class CompletionResult:
provider: ProviderName
model: str
text: str
input_tokens: int | None
output_tokens: int | None
class ChatProvider(Protocol):
name: ProviderName
def complete(
self,
system_prompt: str,
messages: Sequence[ChatMessage],
max_output_tokens: int,
) -> CompletionResult:
...
class OpenAIChatProvider:
name: ProviderName = "openai"
def __init__(self, settings: Settings) -> None:
api_key, model = settings.require_openai()
self._model = model
self._client = OpenAI(
api_key=api_key,
timeout=settings.request_timeout_seconds,
max_retries=0,
)
def complete(
self,
system_prompt: str,
messages: Sequence[ChatMessage],
max_output_tokens: int,
) -> CompletionResult:
response = self._client.chat.completions.create(
model=self._model,
messages=[
{"role": "system", "content": system_prompt},
*[{"role": message.role, "content": message.content} for message in messages],
],
max_tokens=max_output_tokens,
)
text = (response.choices[0].message.content or "").strip()
if not text:
raise RuntimeError("OpenAI returned an empty assistant response.")
usage = response.usage
return CompletionResult(
provider=self.name,
model=response.model,
text=text,
input_tokens=usage.prompt_tokens if usage else None,
output_tokens=usage.completion_tokens if usage else None,
)
class AnthropicChatProvider:
name: ProviderName = "anthropic"
def __init__(self, settings: Settings) -> None:
api_key, model = settings.require_anthropic()
self._model = model
self._client = Anthropic(
api_key=api_key,
timeout=settings.request_timeout_seconds,
max_retries=0,
)
def complete(
self,
system_prompt: str,
messages: Sequence[ChatMessage],
max_output_tokens: int,
) -> CompletionResult:
response = self._client.messages.create(
model=self._model,
system=system_prompt,
messages=[
{"role": message.role, "content": message.content}
for message in messages
],
max_tokens=max_output_tokens,
)
text = "n".join(
block.text
for block in response.content
if getattr(block, "type", None) == "text"
).strip()
if not text:
raise RuntimeError("Anthropic returned no text content.")
usage = response.usage
return CompletionResult(
provider=self.name,
model=response.model,
text=text,
input_tokens=usage.input_tokens if usage else None,
output_tokens=usage.output_tokens if usage else None,
)
def create_provider(name: ProviderName, settings: Settings) -> ChatProvider:
if name == "openai":
return OpenAIChatProvider(settings)
return AnthropicChatProvider(settings)يستخدم عميل OpenAI نمط SDK الحديث الموجّه للكائنات: from openai import OpenAI، ثم client.chat.completions.create(). يعطّل التطبيق إعادات المحاولة في SDK لتبقى سياسة إعادة محاولة واحدة على مستوى التطبيق مسؤولة عن قرارات إعادة المحاولة.
الخطوة ٣: احفظ الجلسات في SQLite
أنشئ storage.py. تعد SQLite مناسبة لهذه الأداة الطرفية المحلية لمستخدم واحد لأنها توفر قاعدة بيانات محلية دائمة دون خادم منفصل. يسترجع استعلام القراءة الصفوف الأحدث أولاً، ثم يعيد ترتيب تلك المجموعة المحددة زمنياً قبل إرسالها إلى النموذج.
from __future__ import annotations
import sqlite3
from pathlib import Path
from uuid import uuid4
from providers import ChatMessage, Role
class ChatStore:
def __init__(self, path: Path) -> None:
self.connection = sqlite3.connect(path)
self.connection.execute("PRAGMA foreign_keys = ON")
self.connection.executescript(
"""
CREATE TABLE IF NOT EXISTS sessions (
id TEXT PRIMARY KEY
);
CREATE TABLE IF NOT EXISTS messages (
id INTEGER PRIMARY KEY AUTOINCREMENT,
session_id TEXT NOT NULL,
role TEXT NOT NULL CHECK(role IN ('user', 'assistant')),
provider TEXT,
content TEXT NOT NULL,
FOREIGN KEY(session_id) REFERENCES sessions(id) ON DELETE CASCADE
);
CREATE INDEX IF NOT EXISTS message_session_order
ON messages(session_id, id);
"""
)
self.connection.commit()
def create_session(self) -> str:
session_id = str(uuid4())
self.connection.execute("INSERT INTO sessions(id) VALUES (?)", (session_id,))
self.connection.commit()
return session_id
def exists(self, session_id: str) -> bool:
return self.connection.execute(
"SELECT 1 FROM sessions WHERE id = ?", (session_id,)
).fetchone() is not None
def add(self, session_id: str, role: Role, content: str, provider: str | None = None) -> None:
self.connection.execute(
"INSERT INTO messages(session_id, role, provider, content) VALUES (?, ?, ?, ?)",
(session_id, role, provider, content),
)
self.connection.commit()
def recent(self, session_id: str, limit: int) -> list[ChatMessage]:
rows = self.connection.execute(
"""
SELECT role, content FROM (
SELECT id, role, content FROM messages
WHERE session_id = ? ORDER BY id DESC LIMIT ?
) ORDER BY id ASC
""",
(session_id, limit),
).fetchall()
return [ChatMessage(role=row[0], content=row[1]) for row in rows]
def clear(self, session_id: str) -> None:
self.connection.execute("DELETE FROM messages WHERE session_id = ?", (session_id,))
self.connection.commit()
def close(self) -> None:
self.connection.close()الخطوة ٤: ابنِ واجهة CLI تفاعلية
أنشئ chat.py. لا تعيد دالة إعادة المحاولة إلا الأخطاء التي تبدو كإخفاق اتصال أو مهلة زمنية أو خطأ من جانب الخادم. وهي لا تعيد كل استثناء. يتطلب المفتاح المفقود أو الإعداد غير الصالح أو الطلب المرفوض تصحيحاً بدلاً من تكرار حركة الشبكة.
from __future__ import annotations
import argparse
import time
from typing import Literal
from rich.console import Console
from rich.markdown import Markdown
from config import get_settings
from providers import ProviderName, create_provider
from storage import ChatStore
console = Console()
SYSTEM_PROMPT = "You are a precise and practical technical assistant. State important assumptions."
def retryable(error: Exception) -> bool:
name = type(error).__name__.lower()
status = getattr(error, "status_code", None)
return "timeout" in name or "connection" in name or (isinstance(status, int) and status >= 500)
def complete_with_retry(provider_name: ProviderName, store: ChatStore, session_id: str) -> object:
settings = get_settings()
provider = create_provider(provider_name, settings)
messages = store.recent(session_id, settings.max_history_messages)
last_error: Exception | None = None
for attempt in range(1, 4):
try:
return provider.complete(SYSTEM_PROMPT, messages, settings.max_output_tokens)
except Exception as error:
last_error = error
if not retryable(error) or attempt == 3:
raise
time.sleep(min(2 ** (attempt - 1), 4))
assert last_error is not None
raise last_error
def arguments() -> argparse.Namespace:
parser = argparse.ArgumentParser(description="Local multi-model terminal chat")
parser.add_argument("--provider", choices=["openai", "anthropic"], default="openai")
parser.add_argument("--session")
return parser.parse_args()
def main() -> None:
args = arguments()
settings = get_settings()
store = ChatStore(settings.database_path)
provider_name: ProviderName = args.provider
session_id = args.session or store.create_session()
if args.session and not store.exists(session_id):
raise SystemExit(f"Session does not exist: {session_id}")
console.print(f"[green]Ready.[/green] provider={provider_name} session={session_id}")
console.print("Commands: /provider openai, /provider anthropic, /new, /clear, /status, /exit")
try:
while True:
try:
prompt = console.input("[bold blue]You > [/bold blue]").strip()
except (EOFError, KeyboardInterrupt):
console.print("n[yellow]Goodbye.[/yellow]")
break
if not prompt:
continue
if prompt == "/exit":
break
if prompt == "/new":
session_id = store.create_session()
console.print(f"[green]New session:[/green] {session_id}")
continue
if prompt == "/clear":
store.clear(session_id)
console.print("[yellow]Current history cleared.[/yellow]")
continue
if prompt == "/status":
console.print(f"provider={provider_name} session={session_id}")
continue
if prompt.startswith("/provider "):
choice = prompt.removeprefix("/provider ").strip().lower()
if choice in {"openai", "anthropic"}:
provider_name = choice
console.print(f"[green]Provider changed to {choice}.[/green]")
else:
console.print("[red]Choose openai or anthropic.[/red]")
continue
if prompt.startswith("/"):
console.print("[red]Unknown command.[/red]")
continue
store.add(session_id, "user", prompt)
try:
result = complete_with_retry(provider_name, store, session_id)
store.add(session_id, "assistant", result.text, result.provider)
console.print(Markdown(result.text))
console.print(
f"[dim]provider={result.provider} model={result.model} "
f"input_tokens={result.input_tokens} output_tokens={result.output_tokens}[/dim]"
)
except Exception as error:
console.print(f"[red]Request failed:[/red] {type(error).__name__}")
console.print("Your user message remains in the local session. Correct configuration or try again.")
finally:
store.close()
if __name__ == "__main__":
main()شغّل التطبيق باستخدام python chat.py --provider anthropic أو python chat.py --provider openai. استخدم /provider anthropic أثناء الجلسة للتبديل صراحةً. تظل المحادثة السابقة المحفوظة متاحة لأن كلا المهايئين يستهلكان بنية الرسائل الداخلية نفسها.
يعني حفظ رسالة المستخدم قبل إرسال الطلب أن الطلب المتقطع أو الفاشل يظل مرئياً في السجل المحلي. وهذا مفيد لأداة محلية، لكنه قد يترك دور مستخدم دون رد من المساعد. ويمكن لعملية نشر أكبر إضافة حالات تسليم مثل قيد الانتظار، ومكتمل، وفاشل.
اختبر طبقة التخزين
أنشئ tests/test_storage.py. تستخدم هذه الاختبارات قاعدة بيانات SQLite مؤقتة ولا تتطلب مفاتيح API أو استدعاءات شبكة للموفر.
from storage import ChatStore
def test_recent_messages_are_chronological(tmp_path):
store = ChatStore(tmp_path / "test.sqlite3")
session = store.create_session()
store.add(session, "user", "one")
store.add(session, "assistant", "two", "openai")
store.add(session, "user", "three")
messages = store.recent(session, 2)
assert [(message.role, message.content) for message in messages] == [
("assistant", "two"),
("user", "three"),
]
store.close()
def test_clear_preserves_session(tmp_path):
store = ChatStore(tmp_path / "test.sqlite3")
session = store.create_session()
store.add(session, "user", "remove")
store.clear(session)
assert store.exists(session)
assert store.recent(session, 20) == []
store.close()python -m pytest -q
python -m py_compile config.py providers.py storage.py chat.py
python chat.py --provider anthropicحدود الإنتاج قبل إضافة الوكلاء
صُمم Claude Sonnet ٥ لأعمال أكثر اعتماداً على الوكلاء، بما يشمل التخطيط واستخدام الأدوات. تعامل مع هذه القدرة بوصفها سبباً لتعزيز حدود تطبيقك، لا لإضعافها. افصل الاقتراحات التي ينشئها النموذج عن التنفيذ. استخدم أدوات ضمن قوائم سماح، ومدخلات محددة النوع، ومهلاً زمنية قصيرة، وفحوص الهوية والتفويض، وسجلات تدقيق، وخطوات موافقة للعمليات ذات الأثر المترتب.
بالنسبة إلى تطبيق ويب متعدد المستخدمين، استبدل واجهة الطرفية المحلية بخلفية مصادَق عليها، وانتقل من SQLite المحلية إلى قاعدة بيانات تناسب احتياجات التزامن في بيئة النشر، وأبقِ مفاتيح API الخاصة بالموفر على الخادم. أضف سجلات تشغيل منظمة تسجل أنواع الأحداث وأسماء الموفرين من دون تخزين المطالبات الخام افتراضياً. فقد تحتوي المطالبات على معلومات أعمال سرية أو كود مصدر أو بيانات شخصية أو مواد تخص العملاء.
وأخيراً، قيّم النماذج باستخدام مهام ممثلة من مؤسستك. قارن جودة المخرجات وزمن الاستجابة وبيانات استخدام الرموز الوصفية عند إرجاعها ونتائج المراجعة البشرية. تعد مجموعة تقييم صريحة أكثر فائدة من افتراض أن موفراً واحداً هو الأفضل لكل أعباء العمل. تمنح طبقة المهايئ المبنية هنا فرق دول الخليج أساساً صغيراً قابلاً للفحص لهذه المقارنة، مع الحفاظ على مسار واضح نحو سير عمل وكلاء أكثر قدرةً وتحكماً.