{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "975684f2-ad7a-4986-b4c4-50b8578e0223",
   "metadata": {},
   "source": [
    "## GitHub Models 基本程式碼範例\n",
    "此範例展示了如何呼叫 OpenAI 的 Chat Completion API。並利用 GitHub 的 AI 模型推論端點以及透過 GitHub Token 呼叫執行。\n",
    "\n",
    "### 前置作業\n",
    "#### 📌 申請 GitHub API Token\n",
    "**1.建立 GitHub Personal Access Token (PAT)：**\n",
    "- 前往 [GitHub Settings](https://github.com/settings/personal-access-tokens)\n",
    "- 進入 Developer settings > Personal access tokens > Fine-grained tokens\n",
    "\n",
    "![](https://cdn-images-1.medium.com/max/800/1*JhvMmQ5v3PbQzYl04plAaQ.png)\n",
    "    \n",
    "- 點選 「Generate new token」，並選擇 Public Repositories (read-only) 權限\n",
    "- 生成 Token 並妥善保存\n",
    "\n",
    "![](https://cdn-images-1.medium.com/max/800/1*JcZ2NVNRj4-ViXmIOYo6uQ.png)\n",
    "\n",
    "#### 📌 設定 Colab Secrets\n",
    "為了安全起見，不建議直接在程式碼中明碼顯示 Token，而是應該使用 Colab Secrets 來存取（如果是本機開發建議使用dotenv管理環境變數）。\n",
    "\n",
    "在 Google Colab 左側選單點擊「🔑 Secrets」\n",
    "- 點擊 「+ Add new secret」\n",
    "- Name 欄位輸入 GITHUB_TOKEN\n",
    "- Value 欄位貼上剛剛在 GitHub 生成的 Token\n",
    "- 點擊「access✓」按鈕允許 Colab 有權限存取金鑰\n",
    "\n",
    "![](https://cdn-images-1.medium.com/max/800/1*k4y8ac_Gyewrjf-n1PvL0w.png)\n",
    "\n",
    "## 👨🏻‍💻 在 Google Colab 執行 API 測試\n",
    "這個範例程式會自動讀取 GitHub Token，透過 GitHub Models API 呼叫 GPT-4o 來測試 LLM 模型的回應能力。程式首先從 Google Colab 的 Secrets 取得 GITHUB_TOKEN，並使用 OpenAI 客戶端 來連接 GitHub Models 伺服器。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d72e1069-b21f-4902-b902-716c826bf078",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import os\n",
    "from openai import OpenAI\n",
    "from google.colab import userdata\n",
    "\n",
    "# 驗證模型需要使用 GitHub 的 Personal Access Token (PAT)。\n",
    "# 你可以在 GitHub 設定中產生 PAT，詳見官方文件：\n",
    "# https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens\n",
    "client = OpenAI(\n",
    "    base_url=\"https://models.inference.ai.azure.com\",  # 設定 API 伺服器的基礎 URL\n",
    "    api_key=userdata.get('GITHUB_TOKEN'),  # 從 Google Colab 的使用者資料中取得 GitHub Token\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d454c97-abe2-459c-a37b-b3bbb391499f",
   "metadata": {},
   "source": [
    "接著，程式發送一個 聊天請求 (chat completion request)，其中包含 System Prompt，設定 AI 為繁體中文問答助手，並讓使用者詢問「法國的首都？」。最後，AI 會根據模型參數 (如 Temperature、Max Tokens、Top P) 生成回應，並將結果輸出。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "110d8b1e-d4cb-4238-b634-39c5d8ccf794",
   "metadata": {},
   "outputs": [],
   "source": [
    "# 發送聊天請求\n",
    "response = client.chat.completions.create(\n",
    "    messages=[\n",
    "        {\n",
    "            \"role\": \"system\",\n",
    "            \"content\": \"你現在是個問答小幫手，並使用繁體中文回答問題。\",  # 設定系統角色，引導 AI 以繁體中文回答\n",
    "        },\n",
    "        {\n",
    "            \"role\": \"user\",\n",
    "            \"content\": \"請問法國的首都？\",  # 使用者的提問\n",
    "        }\n",
    "    ],\n",
    "    model=\"gpt-4o\",  # 指定使用的 AI 模型為 GPT-4o\n",
    "    temperature=1,  # 設定溫度值，影響回答的隨機性（1 代表較具變化性）\n",
    "    max_tokens=4096,  # 設定回應的最大 Token 數（字數限制）\n",
    "    top_p=1  # 設定 Top-p（核取樣），用於控制回應的多樣性\n",
    ")\n",
    "\n",
    "# 印出 AI 的回應內容\n",
    "print(response.choices[0].message.content)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "56db8f92-21b8-45f7-8dea-e2308ce70b6d",
   "metadata": {},
   "source": [
    "這個範例展示了如何使用 Colab + GitHub Models API 來快速測試 LLM 模型的對話能力。你也可以試試看將 model 替換成其他模型，例如嘗試近日熱門的 DeepSeek-R1。"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b9b80434-a72b-48a8-8dbc-cd7d035bbaa2",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.18"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}