History

localizeflow[bot] 2de47cc7f9 chore(i18n): sync translations with latest source changes (chunk 11/20, 100 files)		1 month ago
..
solution	chore(i18n): sync translations with latest source changes (chunk 11/20, 100 files)	1 month ago
README.md	chore(i18n): sync translations with latest source changes (chunk 11/20, 100 files)	1 month ago

README.md

Unescape Escape

使用 AI 建立聊天助手

還記得《星際爭霸戰》中，船員們會隨意與船上的電腦聊天，問它複雜的問題並獲得深思熟慮的回應嗎？在1960年代看似純屬科幻的事情，如今你可以利用你已經熟悉的網頁技術來構建。

在本課程中，我們將使用 HTML、CSS、JavaScript 以及一些後端整合來打造一個 AI 聊天助手。你會發現，透過你已經學習的技能，能連接到可理解上下文並產生有意義回應的強大 AI 服務。

想像 AI 如同你擁有一個龐大的圖書館，不僅能找到資訊，還能把資訊綜合成連貫的答案，並依你具體的問題量身訂做。你不必翻閱成千上萬頁，而是直接獲得有脈絡的回應。

這個整合透過你熟悉的網頁技術協同工作完成。HTML 建立聊天介面，CSS 處理視覺設計，JavaScript 管理使用者互動，後端 API 將每個部分連接到 AI 服務。這彷彿管弦樂團中不同部門共同合作演奏交響曲。

我們本質上是在建立人類自然溝通與機器處理之間的橋梁。你將學習 AI 服務整合的技術實作以及讓互動感覺直覺的設計模式。

課程結束時，AI 整合將不再是神祕的過程，而像是你可以使用的另一個 API。你會了解驅動 ChatGPT、Claude 等應用的基礎架構模式，並使用你已經學習的網頁開發原則。

⚡ 接下來5分鐘你可以做什麼

忙碌開發者快速入門路徑

flowchart LR
    A[⚡ 5 分鐘] --> B[取得 GitHub 令牌]
    B --> C[測試 AI 遊樂場]
    C --> D[複製 Python 程式碼]
    D --> E[查看 AI 回應]

第1分鐘：造訪 GitHub Models Playground 並創建個人存取權杖
第2分鐘：直接在 Playground 介面測試 AI 互動
第3分鐘：點選「Code」頁籤並複製 Python 程式碼片段
第4分鐘：使用你的權杖在本機執行程式碼：GITHUB_TOKEN=your_token python test.py
第5分鐘：觀看你的第一個 AI 回應從自行程式碼生成

快速測試程式碼：

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://models.github.ai/inference",
    api_key="your_token_here"
)

response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Hello AI!"}],
    model="openai/gpt-4o-mini"
)

print(response.choices[0].message.content)

重要原因：5分鐘內，你就能體驗程式化 AI 互動的魔力。這代表著每個 AI 應用的基本區塊。

下面是完成的專案示意圖：

🗺️ 你的 AI 應用開發學習旅程

journey
    title 從網頁開發到 AI 整合
    section 了解 AI 基礎
      發掘生成式 AI 概念: 4: You
      探索 GitHub Models 平台: 6: You
      精通 AI 參數與提示詞: 8: You
    section 後端整合
      建置 Python API 伺服器: 5: You
      實作 AI 函式呼叫: 7: You
      處理非同步操作: 8: You
    section 前端開發
      創建現代聊天介面: 6: You
      精通即時互動: 8: You
      建置響應式使用者體驗: 9: You
    section 專業應用
      部署完整 AI 系統: 7: You
      優化效能模式: 8: You
      創建生產環境應用: 9: You

你的目標：課程結束時，你將構建出一個完整的 AI 驅動應用，使用構成現代 AI 助理（如 ChatGPT、Claude 和 Google Bard）背後的相同技術與模式。

了解 AI：從神秘到掌握

在深入程式碼前，先了解我們正在使用的是什麼。如果你之前用過 API，你會知道基本模式是：送出請求，拿到回應。

AI API 也遵循類似架構，但它不是從資料庫檢索預先儲存的資料，而是根據從大量文本中學習到的模式產生新的回應。想像這就像圖書館目錄系統與知識淵博的圖書館員的差別，後者能從多個來源綜合資訊。

什麼是「生成式 AI」？

試想羅塞塔石碑如何幫助學者理解埃及象形文字，藉由找到已知與未知語言間的對應模式。AI 模型也是如此——它從海量文字中找出語言運作的規律，然後利用這些規律對新問題生成合適回應。

用簡單比較說明：

傳統資料庫：像是索取你的出生證明——每次得到的都是完全相同文件
搜尋引擎：像是請圖書館員找有關貓的書籍——他們會展示可用資料
生成式 AI：像是詢問一位懂貓的朋友——他會用自己的話講述有趣內容，且依你想知道的調整說法

graph LR
    A[您的問題] --> B[人工智慧模型]
    B --> C[模式識別]
    C --> D[內容生成]
    D --> E[情境回應]
    
    F[訓練數據<br/>書籍、文章、網站] --> B

AI 模型如何學習（簡化版）

AI 模型透過接觸包含書籍、文章、對話等的龐大資料集學習。過程中，它們發現以下模式：

書面溝通中思想的結構
常搭配出現的詞彙組合
對話的典型流程
正式與非正式溝通的語境差異

這類似考古學家破解古文明語言：他們分析數千個樣本以理解語法、詞彙及文化背景，最終能以學到的模式解讀新文本。

為何選 GitHub Models？

我們使用 GitHub Models 是因為實務考量——它讓我們能使用企業等級 AI，無需自行架設 AI 基礎設施（相信我，你現在不想自己弄！）。這就像用氣象 API，而不是自己設置氣象站預測天氣。

基本上是「AI 即服務」，最好的是你可以免費開始，隨意嘗試不用怕帳單爆表。

graph LR
    A[前端聊天介面] --> B[你的後端 API]
    B --> C[GitHub 模型 API]
    C --> D[AI 模型處理]
    D --> C
    C --> B
    B --> A

我們會使用 GitHub Models 作為後端整合，透過開發者友善介面，取得專業級 AI 功能。GitHub Models Playground 是測試環境，你可以在那試驗不同 AI 模型，理解它們的能力後再寫程式碼實作。

🧠 AI 應用開發生態系統

mindmap
  root((AI 發展))
    理解 AI
      生成模型
        模式識別
        內容生成
        上下文理解
        回應合成
      AI 參數
        溫度控制
        令牌限制
        Top-p 篩選
        系統提示
    後端架構
      API 整合
        GitHub 模型
        認證
        請求處理
        錯誤管理
      Python 基礎架構
        FastAPI 框架
        非同步操作
        環境安全
        CORS 配置
    前端體驗
      聊天介面
        即時更新
        訊息歷史
        使用者回饋
        加載狀態
      現代網路技術
        ES6 類別
        Async/Await
        DOM 操作
        事件處理
    專業範式
      安全最佳實踐
        令牌管理
        輸入驗證
        XSS 防護
        錯誤邊界
      生產準備
        性能優化
        響應式設計
        易用性
        測試策略

核心原則：AI 應用開發結合傳統網頁開發技巧與 AI 服務整合，打造對使用者來說自然且反應靈敏的智慧應用。

Playground 這麼好用的原因：

試用不同 AI 模型如 GPT-4o-mini、Claude 等（皆免費！）
測試你的構想與提示詞，先行驗證
取得你偏好的程式語言現成程式碼範例
調整創意程度與回應長度，觀察輸出效果差異

玩過一輪後，只要點「Code」頁籤，選擇程式語言，就能取得所需實作程式碼。

設定 Python 後端整合

現在我們用 Python 實作 AI 整合。Python 是 AI 應用好選擇，因其簡潔語法與強大函式庫。我們會從 GitHub Models playground 的程式碼開始，然後重構為一個可重複使用、適合生產環境的函式。

了解基礎實作

從 playground 複製的 Python 程式碼看起來會像這樣。第一次因為有點多不要擔心，我們逐段解釋：

"""Run this model in Python

> pip install openai
"""
import os
from openai import OpenAI

# 要對模型進行驗證，您需要在 GitHub 設定中產生個人存取權杖 (PAT)。
# 請依照此處說明建立您的 PAT 權杖：https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens
client = OpenAI(
    base_url="https://models.github.ai/inference",
    api_key=os.environ["GITHUB_TOKEN"],
)

response = client.chat.completions.create(
    messages=[
        {
            "role": "system",
            "content": "",
        },
        {
            "role": "user",
            "content": "What is the capital of France?",
        }
    ],
    model="openai/gpt-4o-mini",
    temperature=1,
    max_tokens=4096,
    top_p=1
)

print(response.choices[0].message.content)

程式碼說明：

匯入必要工具：os 用來讀取環境變數，OpenAI 用來跟 AI 通訊
設定 OpenAI 用戶端指向 GitHub 的 AI 伺服器，而非直接連接 OpenAI
驗證使用特別的 GitHub 權杖（稍後詳述！）
規劃聊天內容各種「角色」——就像為劇本設演出場景
傳送請求給 AI 並帶入微調的參數
取出回傳資料中真正的回應文字內容

理解訊息角色：AI 對話架構

AI 對話有特定結構，不同「角色」負責不同目的：

messages=[
    {
        "role": "system",
        "content": "You are a helpful assistant who explains things simply."
    },
    {
        "role": "user", 
        "content": "What is machine learning?"
    }
]

就像導演一齣戲：

系統角色：猶如演員的舞台指令——告訴 AI 怎麼表現、要有什麼個性、怎麼回答
使用者角色：實際使用者傳來的問題或訊息
助理角色：AI 的回應（你不會傳送這個，但它會存在對話歷史中）

生活中類比：想像你在派對介紹朋友：

系統訊息：「這是我朋友 Sarah，醫生，擅長用簡單語言說明醫學概念」
用戶訊息：「你能解釋疫苗是怎麼運作的嗎？」
助理回應：Sarah 會像親切醫生回答，而不是律師或廚師

了解 AI 參數：微調回應行為

AI API 呼叫中的數值參數控制模型生成回應的方式。你可以藉此調整 AI 行為，符合不同用途：

溫度（Temperature，0.0 到 2.0）：創意調節旋鈕

作用：控制 AI 回應的創意或可預測程度。

可以想成爵士樂手的即興程度：

Temperature = 0.1：每次演奏同一旋律（高度可預測）
Temperature = 0.7：帶點變化又仍能識別的旋律（平衡創意）
Temperature = 1.5：完全實驗性的爵士樂，有意料之外的轉折（高度不可預測）

# 非常可預測的回答（適合事實性問題）
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "What is 2+2?"}],
    temperature=0.1  # 幾乎總是會說「4」
)

# 有創意的回答（適合腦力激盪）
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Write a creative story opening"}],
    temperature=1.2  # 會生成獨特且出乎意料的故事
)

最大標記數（Max Tokens，1 到 4096+）：回應長度控制器

作用：限制 AI 回應的長度。

標記大約等同英文單字（約 1 標記 = 0.75 英文單字）：

max_tokens=50：短小精悍（像簡訊）
max_tokens=500：一兩段可讀段落
max_tokens=2000：詳盡說明附示例

# 簡短、扼要的回答
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Explain JavaScript"}],
    max_tokens=100  # 強制進行簡短說明
)

# 詳盡、全面的回答
response = client.chat.completions.create(
    messages=[{"role": "user", "content": "Explain JavaScript"}],
    max_tokens=1500  # 允許詳細說明並附上範例
)

聚焦度（Top_p，0.0 到 1.0）：聚焦參數

作用：控制 AI 回應聚焦於最可能的詞彙範圍。

想像 AI 有龐大詞彙庫，詞彙依可能性排序：

top_p=0.1：只考慮前10%最可能的詞（非常聚焦）
top_p=0.9：考慮90%可能詞彙（較有創意）
top_p=1.0：全部納入考量（最大變化度）

舉例：當你問「天空通常是...」

低 top_p：幾乎一定回答「藍色」
高 top_p：可能回答「藍色」、「多雲」、「廣闊」、「變化莫測」、「美麗」等等

組合參數：不同用途的範本配置

# 用於提供事實性且一致的答案（如文件機器人）
factual_params = {
    "temperature": 0.2,
    "max_tokens": 300,
    "top_p": 0.3
}

# 用於創意寫作輔助
creative_params = {
    "temperature": 1.1,
    "max_tokens": 1000,
    "top_p": 0.9
}

# 用於對話式且有幫助的回應（平衡）
conversational_params = {
    "temperature": 0.7,
    "max_tokens": 500,
    "top_p": 0.8
}

quadrantChart
    title AI 參數優化矩陣
    x-axis 低創造力 --> 高創造力
    y-axis 短回應 --> 長回應
    
    quadrant-1 創意內容
    quadrant-2 詳細分析
    quadrant-3 快速事實
    quadrant-4 會話式 AI
    
    Documentation Bot: [0.2, 0.3]
    Customer Service: [0.4, 0.4]
    General Assistant: [0.7, 0.5]
    Creative Writer: [0.9, 0.9]
    Brainstorming Tool: [0.8, 0.8]

理解為何參數重要：不同應用需要不同類型回應。客服機器人應該一致且事實為主（低溫度），創意寫作助理則需富想像且多變（高溫度）。懂得這些參數，能掌握 AI 的個性與回答風格。


**Here's what's happening in this code:**
- **We import** the tools we need: `os` for reading environment variables and `OpenAI` for talking to the AI
- **We set up** the OpenAI client to point to GitHub's AI servers instead of OpenAI directly
- **We authenticate** using a special GitHub token (more on that in a minute!)
- **We structure** our conversation with different "roles" – think of it like setting the scene for a play
- **We send** our request to the AI with some fine-tuning parameters
- **We extract** the actual response text from all the data that comes back

> 🔐 **Security Note**: Never hardcode API keys in your source code! Always use environment variables to store sensitive credentials like your `GITHUB_TOKEN`.

### Creating a Reusable AI Function

Let's refactor this code into a clean, reusable function that we can easily integrate into our web application:

```python
import asyncio
from openai import AsyncOpenAI

# Use AsyncOpenAI for better performance
client = AsyncOpenAI(
    base_url="https://models.github.ai/inference",
    api_key=os.environ["GITHUB_TOKEN"],
)

async def call_llm_async(prompt: str, system_message: str = "You are a helpful assistant."):
    """
    Sends a prompt to the AI model asynchronously and returns the response.
    
    Args:
        prompt: The user's question or message
        system_message: Instructions that define the AI's behavior and personality
    
    Returns:
        str: The AI's response to the prompt
    """
    try:
        response = await client.chat.completions.create(
            messages=[
                {
                    "role": "system",
                    "content": system_message,
                },
                {
                    "role": "user",
                    "content": prompt,
                }
            ],
            model="openai/gpt-4o-mini",
            temperature=1,
            max_tokens=4096,
            top_p=1
        )
        return response.choices[0].message.content
    except Exception as e:
        logger.error(f"AI API error: {str(e)}")
        return "I'm sorry, I'm having trouble processing your request right now."

# Backward compatibility function for synchronous calls
def call_llm(prompt: str, system_message: str = "You are a helpful assistant."):
    """Synchronous wrapper for async AI calls."""
    return asyncio.run(call_llm_async(prompt, system_message))

理解這個改良函式：

接受兩個參數：用戶提示詞及選填系統訊息
提供預設系統訊息以維持通用助手行為
使用適當 Python 型別提示，促進程式碼維護
包含詳盡文件字串說明函式用途與參數
只回傳回應內容，方便用於後端 API
保持相同模型參數，確保 AI 行為一致

系統提示的魔力：編程 AI 性格

如果參數控制 AI 怎麼思考，系統提示控制 AI 覺得自己是誰。說實話，這是與 AI 工作中最酷的部分之一——你基本上是給 AI 一個完整的個性、專業水準和溝通風格。

把系統提示想成為不同角色挑角：不只是擁有一個通用助手，你可以創造各種專家角色。需要有耐心的老師？創意腦力激盪夥伴？嚴肅的商務顧問？改變系統提示即可！

為何系統提示這麼強大

這點很有趣：AI 模型在訓練時見過無數人扮演不同角色和專業水平的對話。當你給 AI 一個明確角色時，彷彿啟動了所有已學到的相關語言模式。

這就像 AI 的角色扮演法：告訴演員「你是一位睿智的老教授」，你會看到他們自動調整姿態、用詞和舉止。AI 對語言模式的處理非常類似。

打造有效系統提示的藝術與科學

優秀系統提示結構：

角色/身份定位：AI 是誰？
專業領域：它懂什麼？
溝通風格：怎麼說話？
具體指令：要聚焦什麼？

# ❌ 模糊的系統提示
"You are helpful."

# ✅ 詳細且有效的系統提示
"You are Dr. Sarah Chen, a senior software engineer with 15 years of experience at major tech companies. You explain programming concepts using real-world analogies and always provide practical examples. You're patient with beginners and enthusiastic about helping them understand complex topics."

帶情境的系統提示範例

看看不同系統提示如何塑造截然不同的 AI 個性：

# 範例 1：耐心的老師
teacher_prompt = """
You are an experienced programming instructor who has taught thousands of students. 
You break down complex concepts into simple steps, use analogies from everyday life, 
and always check if the student understands before moving on. You're encouraging 
and never make students feel bad for not knowing something.
"""

# 範例 2：有創意的合作者
creative_prompt = """
You are a creative writing partner who loves brainstorming wild ideas. You're 
enthusiastic, imaginative, and always build on the user's ideas rather than 
replacing them. You ask thought-provoking questions to spark creativity and 
offer unexpected perspectives that make stories more interesting.
"""

# 範例 3：策略性商業顧問
business_prompt = """
You are a strategic business consultant with an MBA and 20 years of experience 
helping startups scale. You think in frameworks, provide structured advice, 
and always consider both short-term tactics and long-term strategy. You ask 
probing questions to understand the full business context before giving advice.
"""

看系統提示如何影響回應

用相同問題搭配不同系統提示，觀察回應大不同：

問題：「我該如何在網頁應用裡處理使用者身份驗證？」

# 使用教師提示：
teacher_response = call_llm(
    "How do I handle user authentication in my web app?",
    teacher_prompt
)
# 典型回應：「好問題！讓我們把身份驗證分解成簡單步驟。
# 想像它像夜店保全檢查身分證……」

# 使用商業提示：
business_response = call_llm(
    "How do I handle user authentication in my web app?", 
    business_prompt
)
# 典型回應：「從策略角度來看，身份驗證對於用戶
# 信任和法規遵循至關重要。讓我提出一個考慮安全性、
# 用戶體驗和可擴展性的框架……」

進階系統提示技巧

1. 情境設置：給 AI 背景資訊

system_prompt = """
You are helping a junior developer who just started their first job at a startup. 
They know basic HTML/CSS/JavaScript but are new to backend development and databases. 
Be encouraging and explain things step-by-step without being condescending.
"""

2. 輸出格式設定：告訴 AI 如何結構化回應

system_prompt = """
You are a technical mentor. Always structure your responses as:
1. Quick Answer (1-2 sentences)
2. Detailed Explanation 
3. Code Example
4. Common Pitfalls to Avoid
5. Next Steps for Learning
"""

3. 約束條件設定：定義 AI 不該做的事情

system_prompt = """
You are a coding tutor focused on teaching best practices. Never write complete 
solutions for the user - instead, guide them with hints and questions so they 
learn by doing. Always explain the 'why' behind coding decisions.
"""

這對您的聊天助手為何重要

理解系統提示讓您擁有強大能力來創造專門化的 AI 助手：

客服機器人：有幫助、有耐心、瞭解政策
學習導師：鼓勵式、逐步引導、檢查理解
創意夥伴：富有想像力、擴展點子、提問「如果…怎麼辦？」
技術專家：精確、詳細、注重安全

關鍵見解：您不只是呼叫一個 AI API——您是在打造一個符合您特定用例的客製化 AI 個性。這就是現代 AI 應用感覺上量身訂製且實用，而非通用的原因。

🎯 教學檢測：AI 個性程式設計

暫停與反思：您剛學會透過系統提示程式設計 AI 個性。這是現代 AI 應用開發的一項基本技能。

快速自我評估：

您能解釋系統提示與一般使用者訊息的不同嗎？
temperature 與 top_p 參數有何差異？
您會如何為特定用例（例如程式教學）創建系統提示？

實務連結：您學到的系統提示技術被所有主要 AI 應用使用——從 GitHub Copilot 的程式輔助到 ChatGPT 的對話介面。您正在掌握大型科技公司 AI 產品團隊的相同模式。

挑戰問題：您如何設計針對不同用戶類型（初學者 vs 專家）的不同 AI 個性？想想同一底層 AI 模型如何透過提示工程服務不同受眾。

使用 FastAPI 建置 Web API：您的高效能 AI 溝通樞紐

現在讓我們建立將前端連接到 AI 服務的後端。我們將使用 FastAPI，這是一個專為 AI 應用打造的現代 Python 框架。

FastAPI 提供多項優勢：內建非同步支持以處理並行請求、自動生成 API 文件以及極佳效能。您的 FastAPI 伺服器充當中介，接收前端請求、與 AI 服務溝通並返回格式化回應。

為什麼選 FastAPI 作為 AI 應用？

您可能會想：「我不能直接從前端 JavaScript 呼叫 AI 嗎？」或「為什麼要選 FastAPI 而不是 Flask 或 Django？」好問題！

這就是為什麼 FastAPI 非常適合我們的專案：

預設非同步：可以同時處理多個 AI 請求而不會卡住
自動文件：造訪 /docs 即可免費獲得漂亮互動 API 文件頁面
內建驗證：在錯誤發生前捕獲問題
極速效能：是 Python 框架中速度最快的之一
現代 Python：使用最新最優的 Python 功能

而且我們為何需要後端：

安全性：您的 AI API 金鑰就像密碼——如果放在前端 JavaScript，任何查看網站原始碼的人都能偷走並用您的 AI 點數。後端可保護敏感憑證安全。

頻率限制與管控：後端可以控制用戶的請求頻率、實現用戶認證和加入日誌紀錄以追蹤使用情況。

資料處理：您可能想保存對話、過濾不當內容或整合多個 AI 服務。這些邏輯都放在後端。

架構類似用戶端－伺服器模型：

前端：互動的使用介面層
後端 API：請求處理與路由層
AI 服務：外部計算與回應生成
環境變數：安全設定與憑證儲存

理解請求 - 回應流程

讓我們追蹤使用者發送訊息時發生什麼事：

sequenceDiagram
    participant User as 👤 使用者
    participant Frontend as 🌐 前端
    participant API as 🔧 FastAPI 伺服器
    participant AI as 🤖 人工智慧服務
    
    User->>Frontend: 輸入 "Hello AI!"
    Frontend->>API: POST /hello {"message": "Hello AI!"}
    Note over API: 驗證請求<br/>加入系統提示
    API->>AI: 傳送格式化請求
    AI->>API: 回傳 AI 回應
    Note over API: 處理回應<br/>記錄對話
    API->>Frontend: {"response": "Hello! How can I help?"}
    Frontend->>User: 顯示 AI 訊息

理解每一步驟：

用戶互動：人員在聊天介面輸入訊息
前端處理：JavaScript 捕捉輸入並格式化為 JSON
API 驗證：FastAPI 使用 Pydantic 模型自動驗證請求
AI 整合：後端加入上下文（系統提示）並呼叫 AI 服務
回應處理：API 接收 AI 回應並可視需要修改
前端顯示：JavaScript 顯示回應於聊天介面

理解 API 架構

sequenceDiagram
    participant Frontend
    participant FastAPI
    participant AI Function
    participant GitHub Models
    
    Frontend->>FastAPI: POST /hello {"message": "你好 AI！"}
    FastAPI->>AI Function: call_llm(message, system_prompt)
    AI Function->>GitHub Models: API 請求
    GitHub Models->>AI Function: AI 回應
    AI Function->>FastAPI: 回應文字
    FastAPI->>Frontend: {"response": "你好！我能如何幫助你？"}

flowchart TD
    A[使用者輸入] --> B[前端驗證]
    B --> C[HTTP POST 請求]
    C --> D[FastAPI 路由]
    D --> E[Pydantic 驗證]
    E --> F[AI 函式呼叫]
    F --> G[GitHub 模型 API]
    G --> H[回應處理]
    H --> I[JSON 回應]
    I --> J[前端更新]
    
    subgraph "安全層"
        K[CORS 中介軟體]
        L[環境變數]
        M[錯誤處理]
    end
    
    D --> K
    F --> L
    H --> M

建立 FastAPI 應用程式

讓我們一步步建構 API。建立名為 api.py 的檔案並填入以下 FastAPI 代碼：

# api.py
from fastapi import FastAPI, HTTPException
from fastapi.middleware.cors import CORSMiddleware
from pydantic import BaseModel
from llm import call_llm
import logging

# 設定日誌紀錄
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

# 建立 FastAPI 應用程式
app = FastAPI(
    title="AI Chat API",
    description="A high-performance API for AI-powered chat applications",
    version="1.0.0"
)

# 設定跨來源資源共享 (CORS)
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],  # 為生產環境進行適當設定
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 用於請求/回應驗證的 Pydantic 模型
class ChatMessage(BaseModel):
    message: str

class ChatResponse(BaseModel):
    response: str

@app.get("/")
async def root():
    """Root endpoint providing API information."""
    return {
        "message": "Welcome to the AI Chat API",
        "docs": "/docs",
        "health": "/health"
    }

@app.get("/health")
async def health_check():
    """Health check endpoint."""
    return {"status": "healthy", "service": "ai-chat-api"}

@app.post("/hello", response_model=ChatResponse)
async def chat_endpoint(chat_message: ChatMessage):
    """Main chat endpoint that processes messages and returns AI responses."""
    try:
        # 擷取並驗證訊息
        message = chat_message.message.strip()
        if not message:
            raise HTTPException(status_code=400, detail="Message cannot be empty")
        
        logger.info(f"Processing message: {message[:50]}...")
        
        # 呼叫 AI 服務（注意：為提升效能，call_llm 應改為非同步）
        ai_response = await call_llm_async(message, "You are a helpful and friendly assistant.")
        
        logger.info("AI response generated successfully")
        return ChatResponse(response=ai_response)
        
    except HTTPException:
        raise
    except Exception as e:
        logger.error(f"Error processing chat message: {str(e)}")
        raise HTTPException(status_code=500, detail="Internal server error")

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=5000, reload=True)

理解 FastAPI 實作：

匯入 FastAPI 提供現代網頁框架功能，Pydantic 負責資料驗證
建立自動 API 文件（伺服器啟動後可於 /docs 訪問）
啟用 CORS 中介軟體允許不同來源前端請求
定義 Pydantic 模型用於自動請求/回應驗證與文件生成
使用非同步端點以提升同時請求性能
實作適當 HTTP 狀態碼及錯誤處理，搭配 HTTPException
包含結構化日誌便於監控與除錯
提供健康檢查端點以監控服務狀態

FastAPI 相較於傳統框架的主要優勢：

自動驗證：Pydantic 模型確保處理前資料正確無誤
互動文件：造訪 /docs 獲得自動生成、可測試的 API 文件
型別安全：Python 類型註解防止執行時錯誤並提升程式品質
非同步支持：同時處理多個 AI 請求不會阻塞
效能優越：大幅提升實時應用的請求處理速度

理解 CORS：網路的安全守護者

CORS（跨來源資源共享）就像大樓的保全人員，檢查訪客是否被允許入內。讓我們理解為什麼這很重要，並對您的應用有何影響。

什麼是 CORS 以及它存在的理由？

問題：想像如果任何網站都能在您不知情時，代表您對銀行網站發送請求。那將會是安全噩夢！瀏覽器預設透過「同源政策」阻擋這種行為。

同源政策：瀏覽器只允許網頁向來源（domain、port、protocol）相同的網站發送請求。

現實類比：就像公寓大樓的保全——只有住戶（同源）能進入。如果要讓朋友（不同來源）來訪，必須明確通知保全許可。

CORS 在您的開發環境中

開發時，您的前端與後端運行在不同埠口：

前端：http://localhost:3000（或直接開啟 HTML 時為 file://）
後端：http://localhost:5000

即使在同一台電腦上，它們仍被視為「不同來源」！

from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(__name__)
CORS(app)   # 這告訴瀏覽器：「允許其他來源對這個 API 進行請求」

CORS 配置實際做了什麼：

加入特別的 HTTP 頭欄位告知瀏覽器「此跨來源請求被允許」
處理「預檢請求」（瀏覽器在送正式請求前檢查權限）
防止瀏覽器主控台出現「被 CORS 政策阻擋」的錯誤

CORS 安全性：開發 vs 生產

# 🚨 開發：允許所有來源（方便但不安全）
CORS(app)

# ✅ 生產：只允許特定的前端網域
CORS(app, origins=["https://yourdomain.com", "https://www.yourdomain.com"])

# 🔒 進階：不同環境使用不同的來源
if app.debug:  # 開發模式
    CORS(app, origins=["http://localhost:3000", "http://127.0.0.1:3000"])
else:  # 生產模式
    CORS(app, origins=["https://yourdomain.com"])

為何這很重要：在開發中，CORS(app) 就像把前門沒鎖——方便但不安全。生產環境應明確指定可訪問 API 的網站。

常見的 CORS 場景與解決方案

場景	問題	解決方案
本地開發	前端無法訪問後端	FastAPI 加入 CORSMiddleware
GitHub Pages + Heroku	部署後前端無法訪問 API	把您的 GitHub Pages 網址加入 CORS 來源
自訂網域	生產環境發生 CORS 錯誤	將 CORS 來源更新為您的網域
行動應用程式	App 無法訪問 Web API	小心加入 APP 網域或使用 `*`

專家提示：可於瀏覽器開發者工具「網路」標籤查看 CORS 標頭。找尋回應中類似 Access-Control-Allow-Origin 的標頭。

錯誤處理與驗證

注意我們的 API 如何包含適當的錯誤處理：

# 驗證我們是否收到了訊息
if not message:
    return jsonify({"error": "Message field is required"}), 400

重要的驗證原則：

檢查請求前必填欄位是否完整
回傳有意義的 JSON 格式錯誤訊息
使用適當的 HTTP 狀態碼（如 400 代表錯誤請求）
提供清楚回饋幫助前端開發者除錯

設定並啟動您的後端

現在我們的 AI 整合和 FastAPI 伺服器已準備好，讓我們把一切啟動起來。設定程序包括安裝 Python 相依套件、配置環境變數與啟動開發伺服器。

Python 環境設定

讓我們設定 Python 開發環境。虛擬環境就像曼哈頓計劃的分區方法——每個專案有自己的獨立空間與特定工具及依賴，避免不同專案之間互相衝突。

# 導航到你的後端目錄
cd backend

# 創建虛擬環境（就像為你的專案建立一個乾淨的房間）
python -m venv venv

# 啟用它（Linux/Mac）
source ./venv/bin/activate

# 在 Windows 上，使用：
# venv\Scripts\activate

# 安裝必要的套件
pip install openai fastapi uvicorn python-dotenv

我們剛做了什麼：

建立專屬的 Python 環境泡泡，可安裝套件而不影響其他環境
啟用讓終端知道要使用這個特定環境
安裝必要套件：OpenAI 提供 AI 魔力、FastAPI 用於網路 API、Uvicorn 負責執行、python-dotenv 管理安全秘密

主要套件說明：

FastAPI：現代快速網路框架，支援自動文件
Uvicorn：超高速 ASGI 伺服器，可運行 FastAPI 程式
OpenAI：官方 GitHub 模型及 OpenAI API 函式庫
python-dotenv：從 .env 文件安全載入環境變數

環境設定：保護秘密

在啟動 API 前，我們要說明網路開發最重要的課題之一：如何確實地保護秘密。環境變數就像安全保險箱，只有您的應用可以存取。

什麼是環境變數？

想像環境變數像是保險箱 —— 你把貴重物品放裡面，只有你（和你的應用）有鑰匙取出。取代直接在程式碼中寫敏感資料（任何人都能看到），環境變數將資訊安全存放。

差別在於：

錯誤作法：把密碼寫在便利貼貼在電腦螢幕上
正確作法：用安全的密碼管理工具保存且只有自己可訪問

環境變數的重要性

# 🚨 千萬不要這樣做 - API 金鑰對所有人可見
client = OpenAI(
    api_key="ghp_1234567890abcdef...",  # 任何人都可以竊取它！
    base_url="https://models.github.ai/inference"
)

# ✅ 正確做法 - API 金鑰安全儲存
client = OpenAI(
    api_key=os.environ["GITHUB_TOKEN"],  # 只有您的應用程式可以存取這個金鑰
    base_url="https://models.github.ai/inference"
)

硬編碼秘密所造成的問題：

版本控管外洩：任何有存取您 Git 倉庫的人看到您的 API 金鑰
公共倉庫：如果您推送到 GitHub，您的金鑰全網可見
團隊共用：其他開發人員拿到您的個人 API 金鑰
安全漏洞：若金鑰被竊，可濫用您的 AI 點數

建立您的環境檔案

在後端目錄建立 .env 檔案。此檔案用來本地保存您的秘密：

# .env 檔案 - 絕對不可提交到 Git
GITHUB_TOKEN=your_github_personal_access_token_here
FASTAPI_DEBUG=True
ENVIRONMENT=development

理解 .env 文件：

每行寫一個秘密，格式為 KEY=value
等號兩邊無空格
值通常不用引號
註解以 # 開頭

創建 GitHub 個人存取權杖

您的 GitHub 權杖就像特殊密碼，授權您的應用使用 GitHub AI 服務：

權杖創建步驟：

前往 GitHub 設定 → 開發者設定 → 個人存取權杖 → 傳統權杖
點選「產生新權杖（傳統）」
設定有效期限（測試有 30 天，正式可長一點）
選擇權限範圍：勾選「repo」及需要的其他權限
產生權杖並立即複製（無法再查看）
貼上到您的 .env 文件中

# 這是您的令牌範例（這是假的！）
GITHUB_TOKEN=ghp_1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P7Q8R

在 Python 載入環境變數

import os
from dotenv import load_dotenv

# 從 .env 檔案載入環境變數
load_dotenv()

# 現在你可以安全地存取它們
api_key = os.environ.get("GITHUB_TOKEN")
if not api_key:
    raise ValueError("GITHUB_TOKEN not found in environment variables!")

client = OpenAI(
    api_key=api_key,
    base_url="https://models.github.ai/inference"
)

代碼說明：

載入 .env 文件並讓變數可由 Python 讀取
檢查是否存在必要的 token（良好的錯誤處理！）
如果缺少令牌，拋出清楚錯誤
以安全方式使用金鑰，不會在程式碼中曝光

Git 安全：.gitignore 文件

您的 .gitignore 告訴 Git 哪些檔案不該被追蹤或上傳：

# .gitignore - 新增這些行
.env
*.env
.env.local
.env.production
__pycache__/
venv/
.vscode/

為何這很關鍵：加入 .env 於 .gitignore 後，Git 會忽略您的環境檔，避免秘密意外上傳到 GitHub。

不同環境，不同秘密

專業應用會依環境使用不同 API 金鑰：

# .env.development
GITHUB_TOKEN=your_development_token
DEBUG=True

# .env.production
GITHUB_TOKEN=your_production_token
DEBUG=False

重要原因：不希望開發測試影響正式環境 AI 配額，也希望不同環境有不同安全政策。

啟動您的開發伺服器：讓 FastAPI 活起來

現在到了令人興奮的時刻——啟動你的 FastAPI 開發伺服器，看到你的 AI 整合活躍起來！FastAPI 使用 Uvicorn，一個極速的 ASGI 伺服器，專門設計給非同步 Python 應用程式。

了解 FastAPI 伺服器啟動流程

# 方法一：直接執行 Python（包含自動重載）
python api.py

# 方法二：直接使用 Uvicorn（更具控制）
uvicorn api:app --host 0.0.0.0 --port 5000 --reload

當你執行這個指令，幕後發生的事情如下：

1. Python 載入你的 FastAPI 應用程式：

匯入所有必需的函式庫（FastAPI、Pydantic、OpenAI 等）
從 .env 檔案載入環境變數
建立帶有自動文件的 FastAPI 應用實例

2. Uvicorn 設定 ASGI 伺服器：

綁定在埠號 5000，具有非同步請求處理能力
設置具有自動驗證的請求路由
啟動開發用熱重載（偵測檔案更動自動重啟）
產生互動式 API 文件

3. 伺服器開始監聽：

你的終端機顯示：INFO: Uvicorn running on http://0.0.0.0:5000
伺服器可同時處理多個 AI 請求
你的 API 準備就緒，自動文件位於 http://localhost:5000/docs

一切正常時你應該看到的畫面

$ python api.py
INFO:     Will watch for changes in these directories: ['/your/project/path']
INFO:     Uvicorn running on http://0.0.0.0:5000 (Press CTRL+C to quit)
INFO:     Started reloader process [12345] using WatchFiles
INFO:     Started server process [12346]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

理解 FastAPI 輸出：

將監視變更：開發階段啟用自動重載
Uvicorn 運行中：高效能 ASGI 伺服器已啟動
啟動重新加載程序：檔案監視器負責自動重啟
應用啟動完成：FastAPI 應用成功初始化
互動文件可用：造訪 /docs 取得自動 API 文件

測試你的 FastAPI：多種強力方法

FastAPI 提供多種方便的 API 測試方式，包括自動互動式文件：

方法 1：互動式 API 文件（推薦）

打開瀏覽器，前往 http://localhost:5000/docs
你會看到 Swagger UI，所有端點的文件都在這裡
點擊 /hello →「Try it out」→ 輸入測試訊息 →「Execute」
在瀏覽器中直接看到格式化良好的回應

方法 2：基本瀏覽器測試

前往 http://localhost:5000 取得根端點回應
前往 http://localhost:5000/health 檢查伺服器健康狀況
確認你的 FastAPI 伺服器正常運作

方法 2：指令列測試（進階）

# 使用 curl 測試（如果可用）
curl -X POST http://localhost:5000/hello \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello AI!"}'

# 預期回應：
# {"response": "你好！我是你的 AI 助手。今天我能為你做些什麼？"}

方法 3：Python 測試腳本

# test_api.py - 創建此檔案以測試您的 API
import requests
import json

# 測試 API 端點
url = "http://localhost:5000/hello"
data = {"message": "Tell me a joke about programming"}

response = requests.post(url, json=data)
if response.status_code == 200:
    result = response.json()
    print("AI Response:", result['response'])
else:
    print("Error:", response.status_code, response.text)

常見啟動問題排解

錯誤訊息	意義	解決方式
`ModuleNotFoundError: No module named 'fastapi'`	FastAPI 未安裝	在虛擬環境執行 `pip install fastapi uvicorn`
`ModuleNotFoundError: No module named 'uvicorn'`	ASGI 伺服器未安裝	在虛擬環境執行 `pip install uvicorn`
`KeyError: 'GITHUB_TOKEN'`	找不到環境變數	檢查 `.env` 檔案及 `load_dotenv()` 是否正確
`Address already in use`	埠號 5000 被佔用	終止其他使用該埠的程序或換用其他埠號
`ValidationError`	請求資料與 Pydantic 模型不符	確認請求格式符合預期 schema
`HTTPException 422`	無法處理的實體	請求驗證失敗，請檢查 `/docs` 中的正確格式
`OpenAI API error`	AI 服務驗證失敗	確認 GitHub Token 正確且具備足夠權限

開發最佳實踐

熱重載：FastAPI 搭配 Uvicorn 支援在你儲存 Python 程式碼時自動重載。你可以即時修改和測試，不需手動重啟。

# 明確啟用即時重新加載
if __name__ == "__main__":
    app.run(host="0.0.0.0", port=5000, debug=True)  # debug=True 啟用即時重新加載

開發用日誌紀錄：加入日誌，了解發生的情況：

import logging

# 設置日誌記錄
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.route("/hello", methods=["POST"])
def hello():
    data = request.get_json()
    message = data.get("message", "")
    
    logger.info(f"Received message: {message}")
    
    if not message:
        logger.warning("Empty message received")
        return jsonify({"error": "Message field is required"}), 400
    
    try:
        response = call_llm(message, "You are a helpful and friendly assistant.")
        logger.info(f"AI response generated successfully")
        return jsonify({"response": response})
    except Exception as e:
        logger.error(f"AI API error: {str(e)}")
        return jsonify({"error": "AI service temporarily unavailable"}), 500

日誌的重要性：開發時你能看到哪些請求被送出、AI 回應內容與錯誤位置，大大加速除錯效率。

GitHub Codespaces 設定：輕鬆打造雲端開發環境

GitHub Codespaces 就像是一台雲端的強力開發主機，能從任何瀏覽器存取。如果你使用 Codespaces，還需要額外設定，讓後端對前端可見。

Codespaces 網路架構說明

本機開發時，所有東西都運行在同一台電腦上：

後端：http://localhost:5000
前端：http://localhost:3000（或 file://）

在 Codespaces 中，你的開發環境跑在 GitHub 伺服器上，「localhost」的意義不同。GitHub 會自動為你的服務建立公開 URL，但你必須適當設定。

Codespaces 設定步驟

1. 啟動後端伺服器：

cd backend
python api.py

你會看到熟悉的 FastAPI/Uvicorn 啟動訊息，但它跑在 Codespace 環境裡。

2. 設定埠可見性：

在 VS Code 底部面板找到「Ports」標籤
找到列表中的 5000 埠號
右鍵點選埠號 5000
選擇「Port Visibility」→「Public」

為什麼要設為公開？ 預設 Codespace 埠號是私有（只有你可存取）。公開後，前端瀏覽器才能與後端通訊。

3. 取得公開 URL：公開埠口後，你會看到類似以下的 URL：

https://your-codespace-name-5000.app.github.dev

4. 更新前端設定：

// 在您的前端 app.js 中，更新 BASE_URL：
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";

認識 Codespace URL

Codespace URL 有可預測的格式：

https://[codespace-name]-[port].app.github.dev

解析說明：

codespace-name：你的 Codespace 唯一識別碼（通常包含使用者名稱）
port：你的服務埠號（我們的 FastAPI 是 5000）
app.github.dev：GitHub 的 Codespace 應用域名

測試你的 Codespace 設定

1. 直接測試後端：在新分頁開啟你的公共 URL，你應該會看到：

Welcome to the AI Chat API. Send POST requests to /hello with JSON payload containing 'message' field.

2. 使用瀏覽器開發者工具測試：

// 打開瀏覽器控制台並測試您的 API
fetch('https://your-codespace-name-5000.app.github.dev/hello', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({message: 'Hello from Codespaces!'})
})
.then(response => response.json())
.then(data => console.log(data));

Codespaces 與本機開發比較

項目	本機開發	GitHub Codespaces
設定時間	較長（需安裝 Python、相依套件）	即時（預設環境已設好）
URL 存取	`http://localhost:5000`	`https://xyz-5000.app.github.dev`
埠口設定	自動	手動（需開放埠口）
檔案保存	本地機器	GitHub 儲存庫
協作狀況	難共享開發環境	容易分享 Codespace 連結
網路依賴	只需求 AI API 呼叫時	全部過程都須網路

Codespace 開發小貼士

Codespaces 環境變數：你的 .env 檔在 Codespaces 同樣可用，也可以直接在 Codespace 裡設定環境變數：

# 設置當前會話的環境變量
export GITHUB_TOKEN="your_token_here"

# 或添加到您的 .bashrc 以保持持久性
echo 'export GITHUB_TOKEN="your_token_here"' >> ~/.bashrc

埠口管理：

Codespaces 會自動偵測你的應用何時開始監聽某個埠口
你可以同時轉送多個埠口（未來新增資料庫時很有用）
埠口只要 Codespace 運行就持續可用

開發工作流程：

在 VS Code 修改程式碼
FastAPI 自動重載（多虧 Uvicorn reload 模式）
透過公開 URL 立刻測試改動
準備好後 commit 並推送

💡 專業小技巧：開發時收藏你的 Codespace 後端 URL。只要使用同一個 Codespace，名稱穩定，URL 也不會改變。

建立前端聊天介面：人類與 AI 的交會

接下來我們會建立用戶介面——決定人們如何與你的 AI 助手互動的部分。就像最初 iPhone 介面設計，我們專注讓複雜技術變得直覺且自然。

了解現代前端架構

我們的聊天介面屬於「單頁應用程式」（Single Page Application，SPA）。不像舊式網站每次點擊都載入新頁面，我們的應用會平順且即時更新：

舊網站：像是翻讀一本實體書——你跳到全新頁面
我們的聊天應用：就像用手機——一切流暢且無縫更新

graph TD
    A[使用者輸入訊息] --> B[JavaScript 擷取輸入]
    B --> C[驗證與格式化資料]
    C --> D[發送至後端 API]
    D --> E[顯示載入狀態]
    E --> F[接收 AI 回應]
    F --> G[更新聊天介面]
    G --> H[準備下一則訊息]

classDiagram
    class ChatApp {
        +messages: HTMLElement
        +form: HTMLElement
        +input: HTMLElement
        +sendButton: HTMLElement
        +BASE_URL: string
        +API_ENDPOINT: string
        
        +constructor()
        +initializeEventListeners()
        +handleSubmit(event)
        +callAPI(message)
        +appendMessage(text, role)
        +escapeHtml(text)
        +scrollToBottom()
        +setLoading(isLoading)
    }
    
    ChatApp --> DOM : 操作
    ChatApp --> FastAPI : 發送請求

前端開發三大支柱

每個前端應用——從簡單網頁到複雜的 Discord 或 Slack——都是建立在三項核心技術上。它們就像你在網路上看到並互動的所有事物的基礎：

HTML（結構）：你的基礎

決定哪些元素存在（按鈕、文字區、容器）
賦予內容意義（這是標題、這是表單等）
建立所有其他東西的基本架構

CSS（呈現）：你的室內設計師

讓一切看起來漂亮（色彩、字型、排版）
處理不同螢幕尺寸（手機、筆電、平板）
製造流暢動畫與視覺回饋

JavaScript（行為）：你的大腦

回應使用者動作（點擊、輸入、滾動）
與你的後端對話並更新頁面
讓一切互動且動態發生

想像成建築設計：

HTML：結構藍圖（定義空間與關係）
CSS：美學與環境設計（視覺風格與用戶體驗）
JavaScript：機械系統（功能性與互動性）

為什麼現代 JavaScript 架構很重要

我們的聊天應用會使用專業等級的現代 JavaScript 範式。理解這些概念，將幫助你成為更好的開發者：

類別架構：我們會用類別組織程式碼，猶如為物件建造藍圖
Async/Await：處理耗時作業（如 API 呼叫）的現代寫法
事件驅動程式設計：應用回應使用者操作（點擊、按鍵），非一直運行
DOM 操控：根據使用者互動及 API 回應動態更新網頁內容

專案結構設定

建立一個 frontend 目錄，結構如下：

frontend/
├── index.html      # Main HTML structure
├── app.js          # JavaScript functionality
└── styles.css      # Visual styling

架構說明：

區分結構（HTML）、行為（JavaScript）與呈現（CSS）三大關注點
維持簡單易導覽的檔案結構，方便修改與擴充
遵循網頁開發最佳實踐，確保組織與可維護性

建立 HTML 基礎：為無障礙使用語意化結構

我們先從 HTML 結構開始。現代網頁開發強調「語意化 HTML」——使用明確描述用途的 HTML 元素，而非僅著重外觀。這讓應用對螢幕閱讀器、搜尋引擎和其他工具更友善。

語意化 HTML 重要性：想像你要透過電話描述你的聊天應用，你會說「上方有標題的標頭區，中間主要是對話區，底下有個輸入訊息的表單。」語意化 HTML 就是用符合這自然描述的元素。

建立 index.html，採用這樣深思熟慮的標記：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>AI Chat Assistant</title>
    <link rel="stylesheet" href="styles.css">
</head>
<body>
    <div class="chat-container">
        <header class="chat-header">
            <h1>AI Chat Assistant</h1>
            <p>Ask me anything!</p>
        </header>
        
        <main class="chat-messages" id="messages" role="log" aria-live="polite">
            <!-- Messages will be dynamically added here -->
        </main>
        
        <form class="chat-form" id="chatForm">
            <div class="input-group">
                <input 
                    type="text" 
                    id="messageInput" 
                    placeholder="Type your message here..." 
                    required
                    aria-label="Chat message input"
                >
                <button type="submit" id="sendBtn" aria-label="Send message">
                    Send
                </button>
            </div>
        </form>
    </div>
    <script src="app.js"></script>
</body>
</html>

認識每個 HTML 元素與其功能：

文件結構

<!DOCTYPE html>：告訴瀏覽器這是現代 HTML5
<html lang="en">：指定頁面語言，幫助螢幕閱讀器與翻譯工具
<meta charset="UTF-8">：確保正確的國際字元編碼
<meta name="viewport"...>：透過控制縮放與比例，使頁面具備手機響應性

語意元素

<header>：明確標示包含標題與描述的頂部區塊
<main>：指定主要內容區（即對話顯示）
<form>：語意化的用戶輸入表單，有助於鍵盤導覽

無障礙功能

role="log"：告訴螢幕閱讀器這是一個訊息時間軸紀錄區
aria-live="polite"：新訊息溫和地通知螢幕閱讀器，不會打斷使用者
aria-label：為表單控制項提供描述標籤
required：瀏覽器將驗證使用者是否輸入訊息才允許送出

CSS 與 JavaScript 整合

class 屬性：提供 CSS 的樣式掛勾（例如 chat-container、input-group）
id 屬性：讓 JavaScript 找到並操作特定元素
腳本位置：JavaScript 檔案置於底部，確保先載入 HTML

這個結構之所以有效：

邏輯流程：標頭 → 主要內容 → 輸入表單，符合自然閱讀順序
鍵盤可操作：使用者能以 Tab 鍵瀏覽所有互動元素
螢幕閱讀器友善：清楚分區與敘述，協助視障者使用
手機響應式：透過 viewport meta 標籤實現響應式設計
漸進增強：即使 CSS 或 JavaScript 載入失敗，基本功能仍能運作

加入互動式 JavaScript：現代網頁應用邏輯

現在讓我們建立讓聊天室介面活起來的 JavaScript。我們將使用您在專業網頁開發中會遇到的現代 JavaScript 範式，包括 ES6 類別、async/await 和事件驅動程式設計。

了解現代 JavaScript 架構

我們不會寫程序式程式碼（一系列依序執行的函式），而是創建一個基於類別的架構。將類別想像成創建物件的藍圖—就像建築師的藍圖能用來建造多棟房子。

為什麼在網頁應用使用類別？

組織性：所有相關功能都被歸類在一起
可重用性：你可以在同一頁面建立多個聊天實例
維護性：更容易除錯和修改特定功能
專業標準：此模式被 React、Vue 和 Angular 等框架採用

建立 app.js，使用這個現代、結構良好的 JavaScript：

// app.js - 現代聊天應用程式邏輯

class ChatApp {
    constructor() {
        // 取得我們需要操作的 DOM 元素引用
        this.messages = document.getElementById("messages");
        this.form = document.getElementById("chatForm");
        this.input = document.getElementById("messageInput");
        this.sendButton = document.getElementById("sendBtn");
        
        // 在此配置您的後端 URL
        this.BASE_URL = "http://localhost:5000"; // 依您的環境更新此設定
        this.API_ENDPOINT = `${this.BASE_URL}/hello`;
        
        // 在建立聊天應用程式時設定事件監聽器
        this.initializeEventListeners();
    }
    
    initializeEventListeners() {
        // 監聽表單提交（使用者點擊發送或按下 Enter）
        this.form.addEventListener("submit", (e) => this.handleSubmit(e));
        
        // 也監聽輸入欄位中的 Enter 鍵（更好的使用者體驗）
        this.input.addEventListener("keypress", (e) => {
            if (e.key === "Enter" && !e.shiftKey) {
                e.preventDefault();
                this.handleSubmit(e);
            }
        });
    }
    
    async handleSubmit(event) {
        event.preventDefault(); // 防止表單刷新頁面
        
        const messageText = this.input.value.trim();
        if (!messageText) return; // 不要傳送空訊息
        
        // 提供使用者反饋表示正在處理中
        this.setLoading(true);
        
        // 立即將使用者訊息加入聊天（樂觀 UI）
        this.appendMessage(messageText, "user");
        
        // 清除輸入欄位讓使用者可以輸入下一則訊息
        this.input.value = '';
        
        try {
            // 呼叫 AI API 並等待回應
            const reply = await this.callAPI(messageText);
            
            // 將 AI 回應加入聊天
            this.appendMessage(reply, "assistant");
        } catch (error) {
            console.error('API Error:', error);
            this.appendMessage("Sorry, I'm having trouble connecting right now. Please try again.", "error");
        } finally {
            // 無論成功或失敗皆重新啟用介面
            this.setLoading(false);
        }
    }
    
    async callAPI(message) {
        const response = await fetch(this.API_ENDPOINT, {
            method: "POST",
            headers: { 
                "Content-Type": "application/json" 
            },
            body: JSON.stringify({ message })
        });
        
        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }
        
        const data = await response.json();
        return data.response;
    }
    
    appendMessage(text, role) {
        const messageElement = document.createElement("div");
        messageElement.className = `message ${role}`;
        messageElement.innerHTML = `
            <div class="message-content">
                <span class="message-text">${this.escapeHtml(text)}</span>
                <span class="message-time">${new Date().toLocaleTimeString()}</span>
            </div>
        `;
        
        this.messages.appendChild(messageElement);
        this.scrollToBottom();
    }
    
    escapeHtml(text) {
        const div = document.createElement('div');
        div.textContent = text;
        return div.innerHTML;
    }
    
    scrollToBottom() {
        this.messages.scrollTop = this.messages.scrollHeight;
    }
    
    setLoading(isLoading) {
        this.sendButton.disabled = isLoading;
        this.input.disabled = isLoading;
        this.sendButton.textContent = isLoading ? "Sending..." : "Send";
    }
}

// 在頁面載入時初始化聊天應用程式
document.addEventListener("DOMContentLoaded", () => {
    new ChatApp();
});

了解每個 JavaScript 概念

ES6 類別結構：

class ChatApp {
    constructor() {
        // 這會在你建立新的 ChatApp 實例時執行
        // 它就像你的聊天的「設定」函式
    }
    
    methodName() {
        // 方法是屬於類別的函式
        // 它們可以使用 "this" 來存取類別屬性
    }
}

Async/Await 範式：

// 舊方法（回調地獄）：
fetch(url)
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error));

// 現代方法（非同步/等待）：
try {
    const response = await fetch(url);
    const data = await response.json();
    console.log(data);
} catch (error) {
    console.error(error);
}

事件驅動程式設計：我們不會一直檢查事件是否發生，而是「監聽」事件：

// 當表單提交時，執行 handleSubmit
this.form.addEventListener("submit", (e) => this.handleSubmit(e));

// 當按下 Enter 鍵時，也執行 handleSubmit
this.input.addEventListener("keypress", (e) => { /* ... */ });

DOM 操作：

// 建立新元素
const messageElement = document.createElement("div");

// 修改它們的屬性
messageElement.className = "message user";
messageElement.innerHTML = "Hello world!";

// 加入到頁面中
this.messages.appendChild(messageElement);

安全性與最佳實務

XSS 預防：

escapeHtml(text) {
    const div = document.createElement('div');
    div.textContent = text;  // 這會自動轉義 HTML
    return div.innerHTML;
}

原因：如果使用者輸入 <script>alert('hack')</script>，此函式確保它顯示為文字，而非執行程式碼。

錯誤處理：

try {
    const reply = await this.callAPI(messageText);
    this.appendMessage(reply, "assistant");
} catch (error) {
    // 顯示使用者友善的錯誤訊息，而不是使應用程式崩潰
    this.appendMessage("Sorry, I'm having trouble...", "error");
}

使用者體驗考量：

樂觀介面：立即加上使用者訊息，不必等待伺服器回應
載入狀態：等待時禁用按鈕並顯示「傳送中…」
自動捲動：保持最新訊息可見
輸入驗證：不傳送空白訊息
鍵盤快速鍵：Enter 鍵送出訊息（像真實聊天應用）

了解應用程式流程

頁面載入 → 觸發 DOMContentLoaded 事件 → 建立 new ChatApp()
建構子執行 → 取得 DOM 元素參考 → 設定事件監聽器
使用者輸入訊息 → 按下 Enter 或點擊傳送 → 執行 handleSubmit
handleSubmit → 驗證輸入 → 顯示載入狀態 → 呼叫 API
API 回應 → 新增 AI 訊息到聊天 → 重新啟用介面
準備下一則訊息 → 使用者繼續聊天

此架構具擴展性—你可以輕鬆加入訊息編輯、檔案上傳或多重對話串等功能，而無須重寫核心結構。

🎯 教學檢核：現代前端架構

架構理解：您已實作完整單頁應用程式，使用現代 JavaScript 範式。這代表專業級前端開發。

掌握重點概念：

ES6 類別架構：有組織、易維護的程式碼結構
Async/Await 範式：現代非同步程式設計
事件驅動設計：響應式使用者介面設計
安全最佳實務：防止 XSS 與輸入驗證

產業連結：您學到的模式（基於類別的架構、非同步運作、DOM 操作）是 React、Vue、Angular 等現代框架之基礎。您正在建立與實務應用相同的架構思維。

反思問題：您會如何擴充此聊天室應用以處理多重對話或使用者驗證？思考架構更動需求及類別結構的演進。

美化您的聊天室介面

現在，我們用 CSS 建立一個現代且視覺吸引的聊天介面。良好的樣式能讓您的應用顯得專業，且提升整體用戶經驗。我們使用 Flexbox、CSS Grid 和自訂屬性打造響應式且可及性佳的設計。

建立 styles.css，並加入這些完整樣式：

/* styles.css - Modern chat interface styling */

:root {
    --primary-color: #2563eb;
    --secondary-color: #f1f5f9;
    --user-color: #3b82f6;
    --assistant-color: #6b7280;
    --error-color: #ef4444;
    --text-primary: #1e293b;
    --text-secondary: #64748b;
    --border-radius: 12px;
    --shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
}

* {
    margin: 0;
    padding: 0;
    box-sizing: border-box;
}

body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    min-height: 100vh;
    display: flex;
    align-items: center;
    justify-content: center;
    padding: 20px;
}

.chat-container {
    width: 100%;
    max-width: 800px;
    height: 600px;
    background: white;
    border-radius: var(--border-radius);
    box-shadow: var(--shadow);
    display: flex;
    flex-direction: column;
    overflow: hidden;
}

.chat-header {
    background: var(--primary-color);
    color: white;
    padding: 20px;
    text-align: center;
}

.chat-header h1 {
    font-size: 1.5rem;
    margin-bottom: 5px;
}

.chat-header p {
    opacity: 0.9;
    font-size: 0.9rem;
}

.chat-messages {
    flex: 1;
    padding: 20px;
    overflow-y: auto;
    display: flex;
    flex-direction: column;
    gap: 15px;
    background: var(--secondary-color);
}

.message {
    display: flex;
    max-width: 80%;
    animation: slideIn 0.3s ease-out;
}

.message.user {
    align-self: flex-end;
}

.message.user .message-content {
    background: var(--user-color);
    color: white;
    border-radius: var(--border-radius) var(--border-radius) 4px var(--border-radius);
}

.message.assistant {
    align-self: flex-start;
}

.message.assistant .message-content {
    background: white;
    color: var(--text-primary);
    border-radius: var(--border-radius) var(--border-radius) var(--border-radius) 4px;
    border: 1px solid #e2e8f0;
}

.message.error .message-content {
    background: var(--error-color);
    color: white;
    border-radius: var(--border-radius);
}

.message-content {
    padding: 12px 16px;
    box-shadow: var(--shadow);
    position: relative;
}

.message-text {
    display: block;
    line-height: 1.5;
    word-wrap: break-word;
}

.message-time {
    display: block;
    font-size: 0.75rem;
    opacity: 0.7;
    margin-top: 5px;
}

.chat-form {
    padding: 20px;
    border-top: 1px solid #e2e8f0;
    background: white;
}

.input-group {
    display: flex;
    gap: 10px;
    align-items: center;
}

#messageInput {
    flex: 1;
    padding: 12px 16px;
    border: 2px solid #e2e8f0;
    border-radius: var(--border-radius);
    font-size: 1rem;
    outline: none;
    transition: border-color 0.2s ease;
}

#messageInput:focus {
    border-color: var(--primary-color);
}

#messageInput:disabled {
    background: #f8fafc;
    opacity: 0.6;
    cursor: not-allowed;
}

#sendBtn {
    padding: 12px 24px;
    background: var(--primary-color);
    color: white;
    border: none;
    border-radius: var(--border-radius);
    font-size: 1rem;
    font-weight: 600;
    cursor: pointer;
    transition: background-color 0.2s ease;
    min-width: 80px;
}

#sendBtn:hover:not(:disabled) {
    background: #1d4ed8;
}

#sendBtn:disabled {
    background: #94a3b8;
    cursor: not-allowed;
}

@keyframes slideIn {
    from {
        opacity: 0;
        transform: translateY(10px);
    }
    to {
        opacity: 1;
        transform: translateY(0);
    }
}

/* Responsive design for mobile devices */
@media (max-width: 768px) {
    body {
        padding: 10px;
    }
    
    .chat-container {
        height: calc(100vh - 20px);
        border-radius: 8px;
    }
    
    .message {
        max-width: 90%;
    }
    
    .input-group {
        flex-direction: column;
        gap: 10px;
    }
    
    #messageInput {
        width: 100%;
    }
    
    #sendBtn {
        width: 100%;
    }
}

/* Accessibility improvements */
@media (prefers-reduced-motion: reduce) {
    .message {
        animation: none;
    }
    
    * {
        transition: none !important;
    }
}

/* Dark mode support */
@media (prefers-color-scheme: dark) {
    .chat-container {
        background: #1e293b;
        color: #f1f5f9;
    }
    
    .chat-messages {
        background: #0f172a;
    }
    
    .message.assistant .message-content {
        background: #334155;
        color: #f1f5f9;
        border-color: #475569;
    }
    
    .chat-form {
        background: #1e293b;
        border-color: #475569;
    }
    
    #messageInput {
        background: #334155;
        color: #f1f5f9;
        border-color: #475569;
    }
}

CSS 架構說明：

利用 CSS 自訂屬性(變數)以實現統一主題與易於維護
實作 Flexbox 版面，達成響應式設計與正確對齊
包含平滑訊息動畫，不造成干擾
區分使用者訊息、AI 回應與錯誤狀態的視覺效果
支援桌面及行動裝置的響應式設計
考量較低動作偏好與適當對比度的可及性
提供根據使用者系統偏好自動切換暗黑模式

配置您的後端 URL

最後步驟是更新 JavaScript 裡的 BASE_URL 以匹配您的後端伺服器：

// 用於本地開發
this.BASE_URL = "http://localhost:5000";

// 用於 GitHub Codespaces（請替換為您的實際 URL）
this.BASE_URL = "https://your-codespace-name-5000.app.github.dev";

判斷您後端 URL：

本地開發：若前後端皆本地執行，使用 http://localhost:5000
Codespaces：公開 5000 埠後，於端口分頁查看後端 URL
生產環境：部署到託管服務時，替換為實際網域

💡 測試提示：您可直接在瀏覽器開啟根目錄 URL 來測試後端。您應看到 FastAPI 伺服器的歡迎訊息。

測試與部署

現在您已完成前後端元件，讓我們測試它們的整合並探索如何部署以分享您的聊天助理。

本地測試工作流程

依照以下步驟測試完整應用：

graph TD
    A[啟動後端伺服器] --> B[設定環境變數]
    B --> C[測試 API 端點]
    C --> D[於瀏覽器開啟前端]
    D --> E[測試聊天功能]
    E --> F[除錯任何問題]

逐步測試流程：

啟動您的後端伺服器：

cd backend
source venv/bin/activate  # 或在 Windows 上使用 venv\Scripts\activate
python api.py

確認 API 正常工作：
- 在瀏覽器打開 http://localhost:5000
- 您應能看到 FastAPI 伺服器的歡迎訊息
開啟您的前端頁面：
- 進入前端目錄
- 用瀏覽器開啟 index.html
- 或使用 VS Code Live Server 外掛，提供更佳開發體驗
測試聊天功能：
- 在欄位輸入訊息
- 點擊「傳送」或按 Enter
- 確認 AI 有適當回應
- 檢查瀏覽器控制台是否有 JavaScript 錯誤

常見問題排解

問題	症狀	解決方案
CORS 錯誤	前端無法存取後端	確認 FastAPI 已正確配置 CORSMiddleware
API Key 錯誤	回傳 401 未授權	檢查您的 `GITHUB_TOKEN` 環境變數
連線拒絕	前端網路錯誤	確認後端 URL 是否正確且後端伺服器運行中
無 AI 回應	空白或錯誤回應	檢查後端日誌是否有 API 配額或認證問題

常見除錯步驟：

檢查瀏覽器開發者工具 Console 是否有 JavaScript 錯誤
確認 Network 分頁中 API 請求與回應是否成功
檢視後端終端機輸出 Python 錯誤或 API 問題
確認環境變數是否正確載入且可存取

📈 您的 AI 應用開發能力里程碑

timeline
    title 完整的 AI 應用開發旅程
    
    section AI 基礎
        了解生成式 AI
            : 掌握模式識別概念
            : 精通 AI 參數控制
            : 學習提示工程技巧
        
        GitHub 模型整合
            : 探索 AI 服務平台
            : 安全處理身份驗證
            : 優化模型參數
    
    section 後端開發
        Python API 架構
            : 構建 FastAPI 應用
            : 實作非同步操作
            : 建立安全端點
        
        AI 服務整合
            : 連接外部 AI API
            : 處理速率限制
            : 實作錯誤邊界
    
    section 前端精通
        現代 JavaScript 模式
            : 精通 ES6 類別架構
            : 實作 async/await 流程
            : 建置響應式介面
        
        即時用戶體驗
            : 建立動態聊天介面
            : 處理載入狀態
            : 優化用戶互動
    
    section 生產準備
        安全與效能
            : 實作安全令牌管理
            : 防範 XSS 漏洞
            : 優化 API 效能
        
        專業部署
            : 建置可擴充架構
            : 撰寫易維護程式碼
            : 文件化開發流程

🎓 畢業里程碑：您已成功建立完整 AI 驅動應用程式，並使用驅動現代 AI 助理的相同技術與架構模式。這些技能代表傳統網頁開發與尖端 AI 整合的交會點。

🔄 下一階段能力：

準備探索進階 AI 框架（LangChain、LangGraph）
準備建構多模態 AI 應用（文字、影像、語音）
能實作向量資料庫與檢索系統
奠定機器學習及 AI 模型微調基礎

GitHub Copilot Agent 挑戰 🚀

使用 Agent 模式來完成以下挑戰：

描述： 加強聊天助理，加入對話歷史與訊息持久化。此挑戰可幫助您理解如何在聊天應用中管理狀態，並實作資料儲存以提升用戶體驗。

提示： 修改聊天應用，使其包含跨會話持久的對話記錄。加入功能將聊天訊息儲存於本地儲存空間，頁面載入時顯示對話歷史，並加上「清除歷史」按鈕。還要實作輸入動畫指示器及訊息時間戳，讓聊天體驗更真實。

在此了解更多關於 agent mode。

作業：打造您的個人 AI 助理

現在您將打造自己的 AI 助理實作。這不是簡單複製範例程式碼，而是機會將概念應用於貼近您興趣及使用情境的解決方案。

專案需求

讓我們為您的專案建立一個乾淨、組織良好的結構：

my-ai-assistant/
├── backend/
│   ├── api.py          # Your FastAPI server
│   ├── llm.py          # AI integration functions
│   ├── .env            # Your secrets (keep this safe!)
│   └── requirements.txt # Python dependencies
├── frontend/
│   ├── index.html      # Your chat interface
│   ├── app.js          # The JavaScript magic
│   └── styles.css      # Make it look amazing
└── README.md           # Tell the world about your creation

核心實作任務

後端開發：

採用 FastAPI 範例程式碼並做出自己的風格
建立獨特 AI 個性—或許是烹飪助理、創意寫作夥伴或學習助手？
加入完善的錯誤處理，避免應用崩潰
撰寫清楚文件，解釋 API 運作方式

前端開發：

建造直覺且親切的聊天介面
撰寫清晰、現代的 JavaScript 程式碼，讓您引以為傲
設計反映 AI 個性的客製化樣式—活潑多彩？簡潔極簡？隨您喜好決定！
確保在手機與桌面端都良好運作

個人化需求：

選擇獨特名稱及個性給 AI 助理—也許反映您的興趣或解決的問題
自訂視覺設計以符合助理風格
寫出吸引人的歡迎訊息，鼓勵用戶開始聊天
測試以各種問題檢視助理回應

增強點子（選擇性）

想提升專案水準嗎？試試這些有趣的想法：

功能	說明	練習技能
訊息歷史	即使刷新頁面也能記住對話	使用 localStorage、JSON 操作
輸入指示器	回應等待時顯示「AI 正在輸入…」	CSS 動畫、非同步程式設計
訊息時間戳	顯示每則訊息送出時間	日期時間格式化、使用者體驗設計
聊天匯出	讓用戶下載對話內容	檔案操作、資料匯出
主題切換	淺色/深色主題切換	CSS 變數、使用者偏好設定
語音輸入	加入語音轉文字功能	Web API、可及性

測試與文件

品質保證：

測試除錯各種輸入與極端案例
確認響應式設計於不同螢幕尺寸下正常顯示
檢查鍵盤操作與螢幕閱讀器的可及性
驗證 HTML 及 CSS 符合標準

文件需求：

撰寫 README.md，說明專案與執行方式
包含聊天介面運作的截圖
紀錄自訂功能或獨特設計
提供清楚設定指南以協助其他開發者

繳交指南

專案交付項目：

含所有原始碼的完整專案資料夾
README.md，含專案敘述與設定說明
展示聊天助理運作的截圖
簡短心得，說明學習過程和挑戰

評分標準：

功能性：聊天助理是否正常運作？
程式碼品質：程式碼是否井然有序，具備註解且易維護？
設計：介面是否美觀且易用？
創意：實作的獨特性與個人化程度
文件：設定說明是否清楚完整？

💡 成功訣竅：先完成基本需求，再逐步加入增強功能。先打造流暢且完善的核心體驗，再加進高級特性。

解答

Solution

額外挑戰

準備好將您的 AI 助理提升至更高境界？試試這些進階挑戰，深化您對 AI 整合及網頁開發的理解。

個性化定制

真正的魔力來自賦予 AI 助理獨特個性。嘗試不同系統提示，創造專業助理：

專業助理範例：

call_llm(message, "You are a professional business consultant with 20 years of experience. Provide structured, actionable advice with specific steps and considerations.")

創意寫作輔助範例：

call_llm(message, "You are an enthusiastic creative writing coach. Help users develop their storytelling skills with imaginative prompts and constructive feedback.")

技術導師範例：

call_llm(message, "You are a patient senior developer who explains complex programming concepts using simple analogies and practical examples.")

前端增強

透過這些視覺與功能改進，打造更吸引人的聊天介面：

進階 CSS 特性：

實作平滑的訊息動畫與過渡
加入使用 CSS 形狀與漸層的自訂聊天氣泡設計
創造 AI「思考中」輸入指示動畫
設計表情符號回應或訊息評分系統

JavaScript 增強：

加入鍵盤快捷鍵（Ctrl+Enter 送出，Escape 清除輸入）
實作訊息搜尋與篩選功能
建立對話匯出功能（下載為文字或 JSON）
新增自動儲存至 localStorage，防止訊息遺失

進階 AI 整合

多重 AI 個性：

建立下拉選單切換不同 AI 個性
儲存使用者喜愛個性於 localStorage
實作保持對話連貫的上下文切換

智慧回應功能：

增加會話上下文感知（AI 記住先前訊息）
根據對話主題 實作智慧建議
建立常見問題的快速回覆按鈕

🎯 學習目標：這些額外挑戰幫助你理解在生產應用中使用的進階網頁開發模式和 AI 整合技術。

總結與後續步驟

恭喜你！你已經成功從零開始建置了一個完整的 AI 驅動聊天助理。這個專案讓你實際操作了現代網頁開發技術及 AI 整合——這些技能在當今的科技領域中越來越重要。

你已完成的事項

在本課程中，你掌握了多項關鍵技術與概念：