Skip to content

README.fa.md

Latest commit

 

History

History
648 lines (445 loc) · 24.6 KB

README.fa.md

File metadata and controls

648 lines (445 loc) · 24.6 KB
Raw
FreeModels Proxy

FreeModels Proxy

یک پل محلی و سازگار با OpenAI بین FreeModels Chat و Cherry Studio — با پشتیبانی از Streaming و MCP / Tool Call.

FreeModels Proxy روی ویندوز اجرا می‌شود و یک API محلی در اختیار Cherry Studio قرار می‌دهد تا Cherry Studio بتواند از طریق یک Base URL ساده به سرویس FreeModels متصل شود.

Release Downloads License: MIT Python FastAPI Platform

English · فارسی

⭐ مزیت اصلی پروژه

هدف FreeModels Proxy این است که دسترسی موجود FreeModels به Claude Sonnet 5 را به‌صورت رایگان و با سرعت بالای سرویس، از طریق یک API سازگار با OpenAI در اختیار Clientها و Agentهای مختلف قرار دهد.

همین Endpoint محلی می‌تواند به Cherry Studio، Claude Code، OpenCode، Codex، Jan و سایر Clientها و محیط‌های Agent سازگار با OpenAI API متصل شود.

نکته مهم: میزان دسترسی، سرعت، مدل‌ها و محدودیت‌های استفاده توسط سرویس Upstream یعنی FreeModels تعیین می‌شود و ممکن است تغییر کند. خود FreeModels Proxy محدودیت‌های سرویس Upstream را حذف یا تضمین نمی‌کند.

⬇️ دانلود FreeModels Proxy

نسخه Release به‌صورت فایل اجرایی مستقل ویندوز ارائه می‌شود و برای اجرای آن نیازی به Python، pip، PowerShell یا نصب دستی وابستگی‌ها ندارید.

فهرست مطالب

چرا این پروژه ساخته شده است؟

Cherry Studio برای کار با APIهای سازگار با OpenAI طراحی شده است، در حالی که FreeModels Chat سرویس Upstream مخصوص خود را دارد.

FreeModels Proxy این دو محیط را به هم متصل می‌کند:

Cherry Studio
     │
     │ OpenAI-compatible API
     ▼
┌─────────────────────────┐
│    FreeModels Proxy     │
│       127.0.0.1:8000    │
│                         │
│  • سازگاری API          │
│  • Streaming            │
│  • پل Tool / MCP        │
│  • نرمال‌سازی درخواست   │
└────────────┬────────────┘
             │
             ▼
     FreeModels Chat

هدف پروژه ساده است:

Cherry Studio همچنان محیط اصلی Client و Agent باقی بماند و FreeModels Proxy فقط لایه سازگاری بین Cherry Studio و سرویس FreeModels باشد.

امکانات
🪟 لانچر دسکتاپ ویندوز رابط گرافیکی برای Start، Stop، Restart و مشاهده وضعیت Proxy.
🚀 شروع خودکار لانچر می‌تواند هنگام باز شدن برنامه Proxy را به‌صورت خودکار اجرا کند.
🔌 API سازگار با OpenAI API محلی با ساختار مناسب برای کلاینت‌های OpenAI-compatible.
🤖 آماده برای Cherry Studio Base URL پیشنهادی: http://127.0.0.1:8000/v1
⭐ دسترسی به Claude Sonnet 5 طراحی‌شده برای استفاده از دسترسی موجود FreeModels به Claude Sonnet 5 از طریق Clientهای سازگار با OpenAI و Workflowهای Agent.
🆓 دسترسی رایگان Upstream Proxy از دسترسی رایگان ارائه‌شده توسط FreeModels استفاده می‌کند و برای خود Proxy هزینه‌ای بابت API دریافت نمی‌شود.
⚡ دسترسی سریع پاسخ‌ها از طریق Proxy به‌صورت Streaming عبور می‌کنند؛ سرعت نهایی به سرویس FreeModels و شرایط شبکه بستگی دارد.
🧩 سازگار با اکوسیستم Agent قابل استفاده با Cherry Studio، Claude Code، OpenCode، Codex، Jan و سایر ابزارهای سازگار.
🌊 پشتیبانی از Streaming پاسخ‌های Streaming با Server-Sent Events پشتیبانی می‌شوند.
🧰 پل MCP / Tool Call تعریف ابزارهای ارسال‌شده از Cherry Studio دریافت و Tool Callهای مدل به ساختار OpenAI تبدیل می‌شوند.
🔄 حفظ تاریخچه Tool Call پیام‌های assistant دارای Tool Call و نتایج ابزار برای ادامه چرخه Agent حفظ می‌شوند.
🧠 Model Routing درخواست‌ها با شناسه مدل انتخاب‌شده توسط Proxy پردازش و به Upstream ارسال می‌شوند.
📋 کپی سریع Base URL Base URL موردنیاز Cherry Studio مستقیماً از لانچر قابل کپی است.
🧪 دسترسی سریع به Test / Docs از داخل لانچر می‌توانید مستندات API و تست سرویس را باز کنید.
📊 اطلاعات Runtime Host، Port، وضعیت اجرا و اطلاعات اتصال در لانچر نمایش داده می‌شود.
📝 Live Logs فعالیت Proxy و اطلاعات درخواست‌ها در زمان اجرا قابل مشاهده است.
🌐 Host و Port قابل تنظیم بدون تغییر کد می‌توانید Host و Port سرویس را تغییر دهید.
🌍 رابط فارسی و انگلیسی لانچر از دو زبان فارسی و انگلیسی پشتیبانی می‌کند.
📦 فایل EXE مستقل نسخه Release با PyInstaller به فایل اجرایی ویندوز تبدیل می‌شود.
🎨 رابط کاربری مدرن لانچر با طراحی تیره و برندینگ اختصاصی FreeModels Proxy ساخته شده است.
🔒 Local-first به‌صورت پیش‌فرض API روی 127.0.0.1:8000 اجرا می‌شود.

دانلود

پیشنهاد اصلی — نسخه ویندوز

به صفحه آخرین Release بروید:

⬇️ دانلود آخرین نسخه FreeModels Proxy

برای کاربران عادی فایل زیر را دانلود کنید:

FreeModels Proxy.exe

سپس فایل را اجرا کنید.

در نسخه Release نیازی نیست Python یا وابستگی‌های پروژه را به‌صورت دستی نصب کنید.

نسخه سورس

اگر توسعه‌دهنده هستید و می‌خواهید کد را بررسی یا تغییر دهید، می‌توانید Repository را Clone کرده و نسخه Source را اجرا کنید.

نصب و اجرا

نسخه Release

  1. وارد آخرین Release در GitHub شوید.
  2. فایل FreeModels Proxy.exe را دانلود کنید.
  3. فایل را اجرا کنید.
  4. لانچر Proxy را به‌صورت خودکار اجرا می‌کند.
  5. Base URL نمایش‌داده‌شده را در Cherry Studio وارد کنید.

Base URL پیش‌فرض:

http://127.0.0.1:8000/v1

نکته مهم

برای کاربران عادی، استفاده از فایل EXE بهترین گزینه است.

نسخه Source برای توسعه‌دهندگان و افرادی است که قصد تغییر پروژه را دارند.

شروع سریع

بعد از باز شدن لانچر:

  1. مطمئن شوید وضعیت Proxy روی Running است.
  2. Host را روی 127.0.0.1 و Port را روی 8000 بررسی کنید.
  3. Base URL زیر را کپی کنید:
http://127.0.0.1:8000/v1
  1. Cherry Studio را باز کنید.
  2. یک Provider از نوع OpenAI-compatible بسازید یا Provider فعلی را ویرایش کنید.
  3. Base URL را روی http://127.0.0.1:8000/v1 و API Key را روی rkfcode (یا free) قرار دهید.
  4. یکی از مدل‌های ارائه‌شده توسط Proxy را انتخاب کنید.
  5. یک پیام آزمایشی ارسال کنید.

مستندات API نیز از آدرس زیر قابل دسترسی است:

http://127.0.0.1:8000/docs

اتصال به Clientها و Agentهای مختلف

FreeModels Proxy فقط برای Cherry Studio نیست.

چون Proxy یک API محلی سازگار با OpenAI ارائه می‌کند، می‌توان از آن به‌عنوان پل اتصال برای Clientهای هوش مصنوعی، Coding Assistantها و Agentهای مختلف استفاده کرد.

نمونه‌ها

Client / محیط کاربرد
Cherry Studio Chat، Agent و Workflowهای MCP
Claude Code Coding Agent و Agent ترمینالی
OpenCode Coding Agent متن‌باز
Codex Coding Agent / CLI
Jan Client هوش مصنوعی با قابلیت اتصال OpenAI-compatible
سایر Clientهای سازگار هر برنامه‌ای که امکان استفاده از OpenAI-compatible Base URL را داشته باشد

ساختار کلی:

AI Client / Agent
       │
       │ OpenAI-compatible API
       ▼
http://127.0.0.1:8000/v1
       │
       ▼
FreeModels Proxy
       │
       ▼
FreeModels upstream

یعنی اگر Client موردنظر از OpenAI-compatible API پشتیبانی کند، برای اتصال آن به Proxy معمولاً نیازی به Integration اختصاصی جداگانه نیست.

منظور از «رایگان و نامحدود» چیست؟

پروژه بر پایه دسترسی رایگان ارائه‌شده توسط سرویس Upstream یعنی FreeModels طراحی شده است. اگر سرویس FreeModels در حال حاضر دسترسی به Claude Sonnet 5 را بدون API Key پولی و بدون محدودیت عملی قابل‌توجه ارائه کند، Proxy می‌تواند همین دسترسی را از طریق API محلی در اختیار Clientهای سازگار قرار دهد.

با این حال، FreeModels Proxy نمی‌تواند رایگان‌بودن دائمی، استفاده نامحدود، سرعت مشخص یا در دسترس‌بودن دائمی سرویس را تضمین کند؛ این موارد به سرویس Upstream، سیاست‌ها، ظرفیت و شرایط شبکه آن وابسته هستند.

اتصال به Cherry Studio

پیکربندی اولیه پیشنهادی:

تنظیم مقدار
نوع Provider OpenAI-compatible
Base URL http://127.0.0.1:8000/v1
API Key rkfcode یا free
Model یکی از مدل‌های ارائه‌شده توسط /v1/models

تنظیمات پیشنهادی اتصال

وقتی Client از شما یک Provider سازگار با OpenAI می‌خواهد، این مقادیر را وارد کنید:

Base URL: http://127.0.0.1:8000/v1
API Key:  rkfcode

اگر Client مقدار rkfcode را قبول نکرد، مقدار زیر را امتحان کنید:

API Key: free

این API Key در اینجا مقدار احراز هویت مورد انتظار Client/Proxy است و API Key مربوط به حساب پولی OpenAI نیست.

مهم‌ترین بخش، Base URL است. در Clientهای OpenAI-compatible معمولاً باید ریشه API را وارد کرد و خود Client مسیرهایی مانند /chat/completions را اضافه می‌کند. citeturn0search1turn0search7

چرا /v1؟

Endpoint اصلی Chat در Proxy این است:

POST /v1/chat/completions

بنابراین در Cherry Studio باید Base URL زیر را وارد کنید:

http://127.0.0.1:8000/v1

و نباید /chat/completions را به‌صورت دستی به انتهای Base URL اضافه کنید.

API

دریافت لیست مدل‌ها

GET /v1/models

دریافت یک مدل

GET /v1/models/{model_id}

Chat Completions

POST /v1/chat/completions

این Endpoint از پاسخ‌های Streaming با Server-Sent Events پشتیبانی می‌کند.

مسیر سازگاری بدون /v1

POST /chat/completions

این مسیر برای کلاینت‌هایی در نظر گرفته شده که از Prefix /v1 استفاده نمی‌کنند.

مستندات تعاملی FastAPI

http://127.0.0.1:8000/docs

MCP و Tool Call

یکی از دلایل اصلی ساخت این Proxy، حفظ قابلیت‌های Agent و Tool در Cherry Studio است؛ نه اینکه ارتباط فقط به یک چت متنی ساده تبدیل شود.

Proxy می‌تواند:

  1. Toolهای ارسال‌شده توسط Cherry Studio را دریافت کند.
  2. نام ابزارهای MCP را برای قالب مورد انتظار مدل Map کند.
  3. Tool Callهای متنی تولیدشده توسط مدل را تشخیص دهد.
  4. آن‌ها را دوباره به ساختار OpenAI-compatible tool_calls تبدیل کند.
  5. پیام‌های Tool Call و Tool Result را برای Turnهای بعدی حفظ کند.
  6. پاسخ را به‌صورت Streaming به Cherry Studio برگرداند.

نمای کلی:

Cherry Studio
    │
    │ tools + messages
    ▼
FreeModels Proxy
    │
    ├── نرمال‌سازی پیام‌ها
    ├── Map کردن نام ابزارهای MCP
    ├── تبدیل Tool به قالب قابل فهم برای مدل
    ├── تشخیص Tool Call برگشتی
    └── تبدیل به OpenAI tool_calls
    │
    ▼
Cherry Studio Agent
    │
    └── اجرای واقعی MCP Tool

اجرای واقعی ابزار همچنان توسط Cherry Studio انجام می‌شود.

FreeModels Proxy نقش لایه سازگاری و تبدیل بین Client و سرویس مدل را دارد.

پیکربندی

Listener پیش‌فرض

Host: 127.0.0.1
Port: 8000
Base URL: http://127.0.0.1:8000/v1

برای اجرای مستقیم نسخه Python، متغیرهای محیطی زیر نیز قابل استفاده هستند:

FREEMODELS_HOST
FREEMODELS_PORT

مثال:

$env:FREEMODELS_HOST="127.0.0.1"
$env:FREEMODELS_PORT="8001"
python main.py

امکانات قابل کنترل از لانچر

  • Host
  • Port
  • Start / Stop
  • Restart
  • Auto Start
  • Base URL
  • API Docs / Test
  • زبان رابط
  • Runtime information
  • Live logs

تست

تست از مرورگر

بعد از اجرای Proxy آدرس زیر را باز کنید:

http://127.0.0.1:8000/docs

اگر مستندات FastAPI نمایش داده شد، سرویس محلی در حال اجراست.

تست مدل‌ها

آدرس زیر را باز کنید:

http://127.0.0.1:8000/v1/models

باید یک لیست مدل با ساختار OpenAI دریافت کنید.

تست Cherry Studio

Base URL زیر را تنظیم کنید:

http://127.0.0.1:8000/v1

سپس یک پیام کوتاه ارسال کنید.

تست MCP / Tool

برای تست Agent، در Cherry Studio یک Workflow داشته باشید که حداقل یک MCP Tool در اختیار مدل قرار دهد.

Proxy باید Tool definitionها را دریافت کند، Tool Call مدل را به ساختار OpenAI برگرداند و اجازه دهد Cherry Studio چرخه اجرای Tool را ادامه دهد.

حریم خصوصی و امنیت

FreeModels Proxy با رویکرد Local-first طراحی شده است.

  • API محلی به‌صورت پیش‌فرض روی 127.0.0.1 اجرا می‌شود.
  • درخواست Cherry Studio ابتدا به Proxy محلی می‌رسد.
  • Proxy اطلاعات موردنیاز درخواست را به سرویس Upstream مربوط به FreeModels ارسال می‌کند.
  • Proxy برای اجرای عادی به دیتابیس یا سیستم حساب کاربری محلی جداگانه نیاز ندارد.
  • اگر Host را از 127.0.0.1 به یک آدرس دیگر تغییر دهید، ممکن است API از طریق شبکه برای سیستم‌های دیگر قابل دسترسی شود.

نکته امنیتی

این پروژه یک Compatibility Proxy است، نه یک Security Boundary.

اگر سرویس را خارج از localhost در دسترس قرار می‌دهید، قبل از استفاده روی شبکه غیرقابل اعتماد، کنترل‌های مناسب شبکه و فایروال را در نظر بگیرید.

نیازمندی‌ها

برای کاربران عادی

هدف نسخه دسکتاپ، Windows 10 و Windows 11 است.

در نسخه Standalone:

  • Python لازم نیست.
  • pip لازم نیست.
  • PowerShell لازم نیست.
  • FastAPI / httpx / uvicorn نیاز به نصب دستی ندارند.

برای توسعه از سورس

به موارد زیر نیاز دارید:

  • Windows
  • Python 3.x
  • pip
  • پکیج‌های موجود در requirements.txt

ساخت از سورس

Repository را Clone کنید:

git clone https://github.com/rkfcode/FreeModels-Proxy.git
cd FreeModels-Proxy

محیط مجازی را بسازید:

py -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements.txt

لانچر را اجرا کنید:

.venv\Scripts\pythonw.exe launcher.py

ساخت فایل EXE

در پروژه فایل زیر وجود دارد:

build_windows.bat

اجرا:

.\build_windows.bat

فایل نهایی در مسیر زیر ساخته می‌شود:

dist\FreeModels Proxy.exe

ساخت Release با PyInstaller انجام می‌شود و Assetهای برنامه و وابستگی‌های Python نیز در بسته قرار می‌گیرند.

ساختار پروژه

FreeModels-Proxy/
├── launcher.py
├── main.py
├── requirements.txt
├── FreeModels Proxy.bat
├── build_windows.bat
├── README.md
├── README.fa.md
├── .gitignore
└── assets/
    ├── freemodels-proxy-logo.png
    └── freemodels-proxy.ico

وظیفه فایل‌ها

فایل کاربرد
main.py FastAPI Proxy، نرمال‌سازی درخواست، Model Routing، Streaming و Tool Call
launcher.py لانچر دسکتاپ ویندوز و کنترل Runtime
requirements.txt وابستگی‌های Python برای نسخه Source
FreeModels Proxy.bat اجرای نسخه Source
build_windows.bat ساخت نسخه Release با PyInstaller
assets/ لوگو و آیکون ویندوز برنامه

مستندات

در نسخه فعلی، مستندات اصلی پروژه در READMEهای انگلیسی و فارسی و مستندات خود FastAPI قرار دارند.

منبع کاربرد
README انگلیسی معرفی و راه‌اندازی پروژه
README فارسی راهنمای فارسی
http://127.0.0.1:8000/docs مستندات تعاملی FastAPI
/v1/models Endpoint دریافت مدل‌ها
/v1/chat/completions Endpoint اصلی Chat

با توسعه پروژه می‌توان در آینده پوشه docs/ را برای راهنمای نصب، استفاده، معماری، رفع خطا و انتشار اضافه کرد، بدون اینکه ساختار اصلی README تغییر کند.

رفع مشکلات

مشکل چه چیزی را بررسی کنیم؟
Cherry Studio وصل نمی‌شود بررسی کنید Proxy در حال اجرا باشد و Base URL روی http://127.0.0.1:8000/v1 باشد.
/docs باز نمی‌شود وضعیت Proxy، Host و Port را در لانچر بررسی کنید.
/v1/models در دسترس نیست Live Logs و اتصال به Upstream را بررسی کنید.
درخواست یک مدل خطا می‌دهد Model ID انتخاب‌شده و Logهای Proxy را بررسی کنید.
Agent / Tool متوقف می‌شود بررسی کنید Cherry Studio واقعاً tools را ارسال می‌کند و مدل انتخاب‌شده برای Workflow مناسب است.
Port 8000 اشغال است Port را در لانچر تغییر دهید و سپس Base URL جدید را در Cherry Studio قرار دهید.
EXE اجرا نمی‌شود آخرین Release را امتحان کنید و بررسی کنید Windows Security یا Antivirus فایل را مسدود نکرده باشد.
نسخه Source اجرا نمی‌شود .venv را دوباره بسازید و requirements.txt را مجدداً نصب کنید.

برای عیب‌یابی، ابتدا Live Logs داخل لانچر را بررسی کنید.

مشارکت

برای Issue، پیشنهاد و Pull Request خوشحال می‌شویم.

قبل از ارسال تغییرات:

  1. ساختار و سبک فعلی پروژه را حفظ کنید.
  2. در منطق سازگاری Request/Response تغییرات غیرضروری ایجاد نکنید.
  3. اگر Message Handling را تغییر می‌دهید، هم Chat معمولی و هم MCP / Tool Workflow را تست کنید.
  4. README را با رفتار واقعی پروژه هماهنگ نگه دارید.
  5. هیچ Token، Credential یا Secret محلی را Commit نکنید.

مجوز

این پروژه تحت MIT License منتشر شده است.

متن کامل مجوز در فایل LICENSE قرار دارد.

پکیج‌های Third-party مجوزهای مخصوص خود را دارند.

توسعه‌دهنده و حمایت

ساخته‌شده توسط رضا کاظمی.

GitHub Instagram YouTube

Repository:

github.com/rkfcode/FreeModels-Proxy

اگر این پروژه برایتان مفید بود، یک ⭐ در GitHub واقعاً به دیده‌شدن و ادامه توسعه پروژه کمک می‌کند.

حمایت از پروژه

FreeModels Proxy
لایه سازگاری محلی بین FreeModels Chat و Cherry Studio