كيفية توصيل ChatGPT API بمشروع Kotlin: دليل خطوة بخطوة

تعلم Python بسهولة دون إرهاق نظري. حل مهام عملية مع التحقق التلقائي واكتب الكود مباشرة في المتصفح.

لماذا دمج ChatGPT في تطبيق Kotlin؟

تخيل: أنت تكتب تطبيقًا بلغة Kotlin، وفجأة تدرك أنه يفتقر إلى "عقل". يسأل المستخدم سؤالاً، ويتوقف البرنامج. هل يبدو هذا مألوفًا؟ دمج ChatGPT API في Kotlin يحول التطبيق العادي إلى مساعد ذكي. هذه ليست موضة عابرة بل أداة عمل: روبوتات المحادثة، مولدات المحتوى، المترجمون، مساعدو البرمجة — يمكنك بناء كل هذا بنفسك.

في هذه المقالة، لن نضيع وقتًا في المقدمات. سأريك كيفية ربط ChatGPT بمشروعك في غضون 15 دقيقة حرفيًا، باستخدام أدوات Kotlin الحديثة: Retrofit وOkHttp وCoroutines وGson. حتى لو كنت مبتدئًا، فقط اتبع الخطوات — الكود يعمل ومُختبر.

ماذا نحتاج؟ الأدوات والتجهيز

للعمل مع OpenAI API Kotlin، نحتاج إلى مجموعة أدنى. استعد بـ:

مفتاح OpenAI API — سجل في platform.openai.com، وأنشئ مفتاحًا في قسم API keys. احتفظ به سريًا!
بيئة التطوير — IntelliJ IDEA (النسخة المجتمعية كافية) أو Android Studio إذا كنت تطور للتطبيقات المحمولة.
Gradle أو Maven — لإضافة التبعيات.

سنستخدم Retrofit Kotlin كعميل HTTP و Gson Kotlin للعمل مع JSON. لماذا هذين؟ يوفر Retrofit كودًا نظيفًا وتصريحيًا، ويمكن لـ Gson تحويل استجابات API إلى فئات بيانات دون عناء إضافي.

الخطوة 1. إنشاء مشروع وإضافة التبعيات

أنشئ مشروع Gradle جديد (Kotlin/JVM). أضف ما يلي إلى ملف build.gradle.kts:

dependencies {    implementation("com.squareup.retrofit2:retrofit:2.9.0")    implementation("com.squareup.retrofit2:converter-gson:2.9.0")    implementation("com.squareup.okhttp3:okhttp:4.12.0")    implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.8.0")    implementation("com.google.code.gson:gson:2.10.1")}

هام: logging-interceptor اختياري، لكنه سينقذك أثناء التصحيح — سترى ما يُرسل بالفعل إلى الخادم وما يعود. إذا كنت تطور لنظام Android، أضف أيضًا implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.8.0").

الخطوة 2. نماذج البيانات: كيف "يرى" ChatGPT طلبك

يقبل OpenAI API ويعيد JSON صارمًا. لتجنب التحليل اليدوي، سننشئ فئات بيانات. هذا هو أساس أي مثال كود ChatGPT بلغة Kotlin.

// نموذج الطلب لـ ChatGPTdata class ChatRequest(    val model: String = "gpt-4o-mini",  // أرخص وأسرع نموذج    val messages: List<Message>,    val temperature: Double = 0.7)

data class Message(    val role: String,  // "user", "assistant", "system"    val content: String)

// نموذج الاستجابة من ChatGPTdata class ChatResponse(    val choices: List<Choice>?)

data class Choice(    val message: Message?,    val finish_reason: String?)

لاحظ: قمنا بتعيين model إلى gpt-4o-mini — هذا نموذج حديث من OpenAI يكلف pennies لكنه يقدم نتائج لائقة. مثالي للاختبار.

الخطوة 3. Retrofit: تكوين العميل للتواصل مع OpenAI

الآن لننشئ واجهة تصف نقطة النهاية الوحيدة لدينا. هذا هو نهج Retrofit Kotlin الكلاسيكي.

interface OpenAiApi {    @POST("v1/chat/completions")    @Headers("Content-Type: application/json")    suspend fun chatCompletion(        @Header("Authorization") auth: String,        @Body request: ChatRequest    ): ChatResponse}

نقطة أساسية: suspend تعني أن هذه دالة معلقة (مشتقة من Coroutines) — يمكن استدعاؤها فقط داخل نطاق coroutine.

الخطوة 4. إنشاء عميل HTTP وتجربة الطلب

لنقم بتهيئة Retrofit وإنشاء عميل لإجراء أول طلب. هذا هو جوهر ChatGPT API integration in Kotlin.

import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory
import okhttp3.OkHttpClient
import okhttp3.logging.HttpLoggingInterceptor

object ApiClient {
    private const val BASE_URL = "https://api.openai.com/"
    private const val API_KEY = "sk-XXXXX" // استبدل بمفتاحك الفعلي

    private val loggingInterceptor = HttpLoggingInterceptor().apply {
        level = HttpLoggingInterceptor.Level.BODY
    }

    private val httpClient = OkHttpClient.Builder()
        .addInterceptor(loggingInterceptor) // (اختياري) سجل الطلبات/الاستجابات
        .build()

    private val retrofit: Retrofit = Retrofit.Builder()
        .baseUrl(BASE_URL)
        .client(httpClient)
        .addConverterFactory(GsonConverterFactory.create())
        .build()

    val api: OpenAiApi = retrofit.create(OpenAiApi::class.java)
}

لا تنس استبدال sk-XXXXX بمفتاح API الخاص بك! يمكنك حفظه في متغير بيئة أو ملف تكوين، ولكن للاختبار، نص صلب مقبول.

الخطوة 5. إجراء أول طلب إلى ChatGPT

حان الوقت لإحياء التطبيق. اكتب دالة ترسل طلبًا بسيطًا:

import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val request = ChatRequest(
        messages = listOf(
            Message(role = "user", content = "مرحبًا! أخبرني نكتة.")
        )
    )

    val response = ApiClient.api.chatCompletion(
        auth = "Bearer ${ApiClient.API_KEY}",
        request = request
    )

    response.choices?.firstOrNull()?.message?.content?.let {
        println("ChatGPT يقول: $it")
    } ?: println("لم يتم استلام رد!")
}

قم بتشغيل main. في وحدة التحكم، يجب أن ترى سجلات HTTP ثم نكتة. فويلا — تم الاتصال!

الخطوة 6. ماذا لو حدث خطأ؟ معالجة الاستثناءات في Coroutines

في التطبيقات الحقيقية، الأخطاء ضرورية: مفتاح API غير صالح، انتهاء المهلة، تعطل الخادم. استخدم try-catch القياسي مع coroutines:

import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    try {
        val response = ApiClient.api.chatCompletion(
            auth = "Bearer ${ApiClient.API_KEY}",
            request = ChatRequest(
                messages = listOf(Message(role = "user", content = "ما عاصمة فرنسا؟"))
            )
        )
        println(response.choices?.first()?.message?.content ?: "لا رد")
    } catch (e: Exception) {
        println("خطأ: ${e.message}")
    }
}

إذا نفد رصيدك، سترى أخطاء HTTP 429 أو 401. فقط أضف معالجة: تحقق من رمز الحالة، أعد المحاولة بفاصل زمني، أو أبلغ المستخدم.

الخطوة 7. هياكل أكثر تعقيدًا: محادثة بذاكرة

يمكن لـ ChatGPT متابعة السياق إذا مررت تاريخ المحادثة بأكمله. هذا مفيد لروبوتات الدعم أو المساعدين الشخصيين:

val messages = mutableListOf(
    Message(role = "system", content = "أنت مساعد مفيد.")
)

fun chat(userInput: String): String? {
    messages.add(Message(role = "user", content = userInput))

    val response = runBlocking {
        ApiClient.api.chatCompletion(
            auth = "Bearer ${ApiClient.API_KEY}",
            request = ChatRequest(messages = messages)
        )
    }

    val reply = response.choices?.first()?.message?.content
    if (reply != null) {
        messages.add(Message(role = "assistant", content = reply))
    }
    return reply
}