Add zh-tw translations

00-course-setup/translations/tw/README.md

@@ -0,0 +1,151 @@
+# 開始這門課程
+
+我們非常興奮地期待你開始這門課程，看看你會受到什麼啟發來使用生成式 AI 建構！
+
+為了確保您的成功，本頁概述了設定步驟、技術需求以及在需要時獲取幫助的地方。
+
+## 設定步驟
+
+要開始這門課程，你需要完成以下步驟。
+
+### 1. 複製這個 Repo
+
+[複製這個整個 repo](https://github.com/microsoft/generative-ai-for-beginners/fork?WT.mc_id=academic-105485-koreyst) 到你自己的 GitHub 帳號，以便更改任何程式碼並完成挑戰。你也可以[標記 (🌟) 這個 repo](https://docs.github.com/en/get-started/exploring-projects-on-github/saving-repositories-with-stars?WT.mc_id=academic-105485-koreyst) 以更容易找到它和相關的 repo。
+
+### 2. 建立一個程式碼空間
+
+為了避免在執行程式碼時出現任何相依性問題，我們建議在[GitHub Codespaces](https://github.com/features/codespaces?WT.mc_id=academic-105485-koreyst)中執行本課程。
+
+這可以通過在您分叉的這個 repo 版本上選擇 `程式碼` 選項並選擇 **Codespaces** 選項來建立。
+
+![顯示按鈕以建立程式碼空間的對話框](../../images/who-will-pay.webp?WT.mc_id=academic-105485-koreyst)
+
+### 3. 儲存您的 API 金鑰
+
+保持您的 API 金鑰安全是建構任何類型應用程式時的重要事項。我們建議不要將任何 API 金鑰直接儲存在您的程式碼中。如果將這些詳細資訊提交到公共儲存庫，可能會導致安全問題，甚至在被惡意使用者利用時產生不必要的費用。
+
+## 如何在本地電腦上執行
+
+要在本機電腦上執行程式碼，你需要安裝某個版本的[Python](https://www.python.org/downloads/?WT.mc_id=academic-105485-koreyst)。
+
+要使用這個儲存庫，你需要複製它:
+
+```shell
+git clone https://github.com/microsoft/generative-ai-for-beginners
+cd generative-ai-for-beginners
+```
+
+一旦你檢查完所有內容，就可以開始了!
+
+### 安裝 Miniconda (可選步驟)
+
+[Miniconda](https://conda.io/en/latest/miniconda.html?WT.mc_id=academic-105485-koreyst) 是一個輕量級的安裝程式，用於安裝 [Conda](https://docs.conda.io/en/latest?WT.mc_id=academic-105485-koreyst)、Python 以及一些套件。
+Conda 本身是一個套件管理器，使得設定和切換不同的 Python [**虛擬環境**](https://docs.python.org/3/tutorial/venv.html?WT.mc_id=academic-105485-koreyst)和套件變得容易。它也方便用於安裝無法通過 `pip` 獲取的套件。
+
+你可以按照[MiniConda 安裝指南](https://docs.anaconda.com/free/miniconda/#quick-command-line-install?WT.mc_id=academic-105485-koreyst)來設定。
+
+安裝 Miniconda 後，你需要複製這個[repository](https://github.com/microsoft/generative-ai-for-beginners/fork?WT.mc_id=academic-105485-koreyst) (如果你還沒有的話)
+
+接下來，你需要建立一個虛擬環境。要使用 Conda 來完成此操作，請繼續建立一個新的環境檔案 (_environment.yml_)。如果你正在使用 Codespaces，請在 `.devcontainer` 目錄中建立此檔案，因此為 `.devcontainer/environment.yml`。
+
+請繼續並使用以下程式碼片段填充您的環境文件:
+
+```yml
+name: <environment-name>
+channels:
+ - defaults
+dependencies:
+- python=<python-version>
+- openai
+- python-dotenv
+```
+
+環境文件指定了我們需要的相依套件。`<environment-name>` 指的是你想用於 Conda 環境的名稱，而 `<python-version>` 是你想使用的 Python 版本，例如，`3` 是最新的 Python 主要版本。
+
+完成後，您可以在命令列/終端機中執行以下命令來建立您的 Conda 環境
+
+```bash
+conda env create --name ai4beg --file .devcontainer/environment.yml # .devcontainer 子路徑僅適用於 Codespace 設定
+conda activate ai4beg
+```
+
+請參考[Conda 環境指南](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html?WT.mc_id=academic-105485-koreyst)如果你遇到任何問題。
+
+### 使用 Visual Studio Code 搭配 Python 支援擴充功能
+
+我們建議在本課程中使用安裝了[Python 支援擴充功能](https://marketplace.visualstudio.com/items?itemName=ms-python.python&WT.mc_id=academic-105485-koreyst)的[Visual Studio Code (VS Code)](http://code.visualstudio.com/?WT.mc_id=academic-105485-koreyst)編輯器。不過，這只是建議，並不是絕對的要求。
+
+> **注意**: 通過在 VS Code 中打開課程儲存庫，你可以選擇在容器中設定專案。這是因為在課程儲存庫中發現的[特殊 `.devcontainer`](https://code.visualstudio.com/docs/devcontainers/containers?itemName=ms-python.python&WT.mc_id=academic-105485-koreyst)目錄。更多內容稍後介紹。
+
+> **注意**: 一旦你複製並在 VS Code 中打開目錄，它會自動建議你安裝一個 Python 支援擴充套件。
+
+> **注意**: 如果 VS Code 建議你在容器中重新開啟這個儲存庫，請拒絕此請求以使用本地安裝的 Python 版本。
+
+### 在瀏覽器中使用 Jupyter
+
+你也可以在瀏覽器中使用[Jupyter 環境](https://jupyter.org?WT.mc_id=academic-105485-koreyst)來進行專案。經典的 Jupyter 和 [Jupyter Hub](https://jupyter.org/hub?WT.mc_id=academic-105485-koreyst)都提供了相當愉快的開發環境，具有自動完成、程式碼高亮等功能。
+
+要在本地啟動 Jupyter，請前往終端機/命令列，導航到課程目錄，並執行:
+
+```bash
+jupyter notebook
+```
+
+或
+
+```bash
+jupyterhub
+```
+
+這將啟動一個 Jupyter 實例，並且訪問它的 URL 將顯示在命令行視窗中。
+
+一旦你訪問該 URL，你應該會看到課程大綱並能夠導航到任何 `*.ipynb` 文件。例如，`08-building-search-applications/python/oai-solution.ipynb`。
+
+### 執行在容器中
+
+設定所有內容在您的電腦或 Codespace 上的替代方法是使用一個[容器](https://en.wikipedia.org/wiki/Containerization_(computing)?WT.mc_id=academic-105485-koreyst)。課程儲存庫中的特殊 `.devcontainer` 資料夾使 VS Code 能夠在容器內設定專案。在 Codespaces 之外，這將需要安裝 Docker，坦白說，這涉及一些工作，因此我們只建議有容器工作經驗的人使用。
+
+使用 GitHub Codespaces 時，保持 API 金鑰安全的最佳方法之一是使用 Codespace Secrets。請按照[Codespaces secrets management](https://docs.github.com/en/codespaces/managing-your-codespaces/managing-secrets-for-your-codespaces?WT.mc_id=academic-105485-koreyst)指南來了解更多資訊。
+
+## 課程和技術需求
+
+這門課程有6個概念課和6個程式碼課。
+
+在程式碼課程中，我們使用 Azure OpenAI 服務。您將需要訪問 Azure OpenAI 服務和一個 API 金鑰來執行這段程式碼。您可以通過[完成此申請](https://azure.microsoft.com/products/ai-services/openai-service?WT.mc_id=academic-105485-koreyst)來申請訪問權限。
+
+在等待您的應用程式處理時，每個編碼課程還包括一個 `README.md` 文件，您可以在其中查看程式碼和輸出。
+
+## 第一次使用 Azure OpenAI 服務
+
+如果這是您第一次使用 Azure OpenAI 服務，請按照此指南了解如何[建立和部署 Azure OpenAI 服務資源](https://learn.microsoft.com/azure/ai-services/openai/how-to/create-resource?pivots=web-portal&WT.mc_id=academic-105485-koreyst)。
+
+## 第一次使用 OpenAI API
+
+如果這是您第一次使用 OpenAI API，請按照指南[建立和使用介面](https://platform.openai.com/docs/quickstart?context=pythont&WT.mc_id=academic-105485-koreyst)。
+
+## 認識其他學習者
+
+我們已經在我們的官方[AI 社群 Discord 伺服器](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst)中建立了頻道，以便與其他學習者會面。這是一個與其他志同道合的企業家、建構者、學生和任何希望在生成式 AI 中提升的人聯繫的好方法。
+
+[![加入 discord 頻道](https://dcbadge.vercel.app/api/server/ByRwuEEgH4)](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst)
+
+專案團隊也會在這個 Discord 伺服器上幫助任何學習者。
+
+## 貢獻
+
+這門課程是一個開放原始碼計劃。如果您看到改進的地方或問題，請建立一個[Pull Request](https://github.com/microsoft/generative-ai-for-beginners/pulls?WT.mc_id=academic-105485-koreyst)或記錄一個[GitHub issue](https://github.com/microsoft/generative-ai-for-beginners/issues?WT.mc_id=academic-105485-koreyst)。
+
+專案團隊將追蹤所有貢獻。對開放原始碼做出貢獻是建立你在生成式 AI 領域職業生涯的驚人方式。
+
+大多數的貢獻需要您同意貢獻者許可協議（CLA），聲明您有權並實際上授予我們使用您的貢獻的權利。詳情請訪問[CLA, Contributor License Agreement website](https://cla.microsoft.com?WT.mc_id=academic-105485-koreyst)。
+
+重要事項: 在翻譯此 repo 中的文字時，請確保不要使用機器翻譯。我們將通過社群驗證翻譯，因此請僅在您精通的語言中自願進行翻譯。
+
+當你提交一個拉取請求時，CLA-bot 會自動判斷你是否需要提供 CLA 並適當地裝飾 PR (例如，標籤、評論)。只需按照 bot 提供的指示操作。你只需在所有使用我們 CLA 的儲存庫中執行一次此操作。
+
+此專案已採用[Microsoft 開放原始碼行為準則](https://opensource.microsoft.com/codeofconduct/?WT.mc_id=academic-105485-koreyst)。如需更多資訊，請閱讀行為準則常見問題或聯絡[Email opencode]([email protected])以獲取任何其他問題或意見。
+
+## 讓我們開始吧
+
+現在你已經完成了完成這門課程所需的步驟，讓我們開始[介紹生成式 AI 和 LLMs](../../../01-introduction-to-genai/translations/tw/README.md?WT.mc_id=academic-105485-koreyst)。
+

00-course-setup/translations/tw/SETUP.md

@@ -0,0 +1,136 @@
+# 設定 Your Dev Environment
+
+我們設定了這個資料庫和課程，並使用[開發容器](https://containers.dev?WT.mc_id=academic-105485-koreyst)，該容器具有通用執行環境，可以支援 Python3、.NET、Node.js 和 Java 開發。相關配置定義在此資料庫根目錄的 `.devcontainer/` 資料夾中的 `devcontainer.json` 文件中。
+
+要啟動開發容器，請在[GitHub Codespaces](https://docs.github.com/en/codespaces/overview?WT.mc_id=academic-105485-koreyst)（用於雲端託管的執行環境）或[Docker Desktop](https://docs.docker.com/desktop/?WT.mc_id=academic-105485-koreyst)（用於本地設備託管的執行環境）中啟動它。閱讀[此文件](https://code.visualstudio.com/docs/devcontainers/containers?WT.mc_id=academic-105485-koreyst)以獲取有關開發容器在 VS Code 中如何工作的更多詳細資訊。
+
+> [!TIP]  
+> 我們建議使用 GitHub Codespaces 來快速開始並減少努力。它為個人帳戶提供慷慨的[免費使用配額](https://docs.github.com/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces#monthly-included-storage-and-core-hours-for-personal-accounts?WT.mc_id=academic-105485-koreyst)。配置[超時](https://docs.github.com/codespaces/setting-your-user-preferences/setting-your-timeout-period-for-github-codespaces?WT.mc_id=academic-105485-koreyst)以停止或刪除不活動的 codespaces 以最大化您的配額使用。
+
+## 1. 執行指派任務
+
+每節課將有_可選的_作業，可能會以一種或多種程式語言提供，包括: Python、.NET/C#、Java 和 JavaScript/TypeScript。本節提供與執行這些作業相關的一般指導。
+
+### 1.1 Python 指派
+
+Python 指派是以應用程式（`.py` 檔案）或 Jupyter 筆記本（`.ipynb` 檔案）提供。
+
+- 要執行筆記本，請在 Visual Studio Code 中打開它，然後點擊 _Select Kernel_ (在右上角)，並選擇顯示的預設 Python 3 選項。現在你可以 _Run All_ 來執行筆記本。
+- 要從命令列執行 Python 應用程式，請遵循特定作業的指示，以確保選擇正確的檔案並提供所需的參數。
+
+## 2. 設定提供者
+
+作業**可能**也會被設定為通過像 OpenAI、Azure 或 Hugging Face 這樣的支援服務提供者來對抗一個或多個大型語言模型（LLM）部署。這些提供一個_託管端點_（API），我們可以使用正確的憑證（API 金鑰或令牌）以程式化方式訪問。在本課程中，我們討論這些提供者:
+
+- [OpenAI](https://platform.openai.com/docs/models?WT.mc_id=academic-105485-koreyst) 包含多樣化模型，包括核心的 GPT 系列。
+ - [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/?WT.mc_id=academic-105485-koreyst) 提供專注於企業準備的 OpenAI 模型
+ - [Hugging Face](https://huggingface.co/docs/hub/index?WT.mc_id=academic-105485-koreyst) 提供開放原始碼模型和推論伺服器
+
+**你將需要使用你自己的帳戶來完成這些練習**。作業是可選的，所以你可以根據自己的興趣選擇設定一個、全部或不設定任何提供者。以下是一些註冊的指導：
+
+| 註冊 | 費用 | API 金鑰 | 操作平台 | 評論 |
+|:---|:---|:---|:---|:---|
+| [OpenAI](https://platform.openai.com/signup?WT.mc_id=academic-105485-koreyst)| [價格](https://openai.com/pricing#language-models?WT.mc_id=academic-105485-koreyst)| [基於專案](https://platform.openai.com/api-keys?WT.mc_id=academic-105485-koreyst) | [無程式碼, 網頁](https://platform.openai.com/playground?WT.mc_id=academic-105485-koreyst) | 多種模型可用 |
+| [Azure](https://aka.ms/azure/free?WT.mc_id=academic-105485-koreyst)| [價格](https://azure.microsoft.com/pricing/details/cognitive-services/openai-service/?WT.mc_id=academic-105485-koreyst)| [SDK 快速入門](https://learn.microsoft.com/azure/ai-services/openai/quickstart?WT.mc_id=academic-105485-koreyst)| [Studio 快速入門](https://learn.microsoft.com/azure/ai-services/openai/quickstart?WT.mc_id=academic-105485-koreyst) |  [必須提前申請訪問](https://learn.microsoft.com/azure/ai-services/openai/?WT.mc_id=academic-105485-koreyst)|
+| [Hugging Face](https://huggingface.co/join?WT.mc_id=academic-105485-koreyst) | [價格](https://huggingface.co/pricing) | [存取權杖](https://huggingface.co/docs/hub/security-tokens?WT.mc_id=academic-105485-koreyst) | [Hugging Chat](https://huggingface.co/chat/?WT.mc_id=academic-105485-koreyst)| [Hugging Chat 有限的模型](https://huggingface.co/chat/models?WT.mc_id=academic-105485-koreyst) |
+| | | | | |
+
+按照以下指示來_配置_此儲存庫以供不同提供者使用。需要特定提供者的作業將在其檔案名中包含以下標籤之一:
+
+- `aoai` - 需要 Azure OpenAI 端點, 金鑰
+ - `oai` - 需要 OpenAI 端點, 金鑰
+ - `hf` - 需要 Hugging Face token
+
+您可以設定一個、沒有或所有提供者。相關的分配將在缺少憑證時簡單地出錯。
+
+###  2.1. 建立 `.env` 文件
+
+我們假設您已經閱讀了上述指南並註冊了相關提供者，並獲得了所需的身份驗證憑證(API_KEY 或 token)。在 Azure OpenAI 的情況下，我們假設您還擁有一個有效的 Azure OpenAI 服務部署(endpoint)，並至少部署了一個 GPT 模型以完成聊天。
+
+下一步是按如下方式配置你的**本地環境變數**:
+
+1. 在根目錄中查找 `.env.copy` 文件，內容應如下所示:
+
+   ```bash
+   # OpenAI Provider
+   OPENAI_API_KEY='<add your OpenAI API key here>'
+
+   ## Azure OpenAI
+   AZURE_OPENAI_API_VERSION='2024-02-01' # Default is set!
+   AZURE_OPENAI_API_KEY='<add your AOAI key here>'
+   AZURE_OPENAI_ENDPOINT='<add your AOIA service endpoint here>'
+   AZURE_OPENAI_DEPLOYMENT='<add your chat completion model name here>' 
+   AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='<add your embeddings model name here>'
+
+   ## Hugging Face
+   HUGGING_FACE_API_KEY='<add your HuggingFace API or token here>'
+   ```
+
+2. 使用以下命令將該文件複製到 `.env`。此文件已被 _gitignore-d_，以保護秘密資訊。
+
+   ```bash
+   cp .env.copy .env
+   ```
+
+3. 按照下一節中的描述填寫值（替換 `=` 右側的佔位符）。
+
+3. (選項) 如果您使用 GitHub Codespaces，您可以選擇將環境變數保存為與此存儲庫關聯的 _Codespaces secrets_。在這種情況下，您不需要設置本地 .env 文件。**但是，請注意，此選項僅在您使用 GitHub Codespaces 時有效。**如果您使用 Docker Desktop，仍然需要設置 .env 文件。
+
+### 2.2. 填寫 `.env` 檔案
+
+讓我們快速看一下變數名稱，以了解它們代表什麼:
+
+| Variable  | Description  |
+| :--- | :--- |
+| HUGGING_FACE_API_KEY | 這是您在個人資料中設定的使用者存取權杖 |
+| OPENAI_API_KEY | 這是用於非 Azure OpenAI 端點服務的授權金鑰 |
+| AZURE_OPENAI_KEY | 這是用於該服務的授權金鑰 |
+| AZURE_OPENAI_ENDPOINT | 這是 Azure OpenAI 資源的部署端點 |
+| AZURE_OPENAI_DEPLOYMENT | 這是 _文本生成_ 模型的部署端點 |
+| AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT | 這是 _文本嵌入_ 模型的部署端點 |
+| | |
+
+注意: 最後兩個 Azure OpenAI 變數分別反映了聊天完成（文字產生）和向量搜尋（嵌入）的預設模型。設定它們的說明將在相關作業中定義。
+
+### 2.3 設定 Azure: 從 Portal
+
+Azure OpenAI 端點和金鑰值可以在 [Azure Portal](https://portal.azure.com?WT.mc_id=academic-105485-koreyst) 找到，所以讓我們從那裡開始。
+
+1. 前往 [Azure Portal](https://portal.azure.com?WT.mc_id=academic-105485-koreyst)
+1. 點擊側邊欄中的 **Keys and Endpoint** 選項（左側選單）。
+1. 點擊 **Show Keys** - 你應該會看到以下內容: KEY 1, KEY 2 和 Endpoint。
+1. 使用 KEY 1 的值作為 AZURE_OPENAI_KEY
+1. 使用 Endpoint 的值作為 AZURE_OPENAI_ENDPOINT
+
+接下來，我們需要已部署的特定模型的端點。
+
+1. 在側邊欄（左側選單）中點擊 **Model deployments** 選項以獲取 Azure OpenAI 資源。
+1. 在目標頁面中，點擊 **Manage Deployments**
+
+這將帶你到 Azure OpenAI Studio 網站，我們會在那裡找到如下所述的其他值。
+
+### 2.4 設定 Azure: 從 Studio
+
+1. 按照上述說明從你的資源導航到 [Azure OpenAI Studio](https://oai.azure.com?WT.mc_id=academic-105485-koreyst)。
+1. 點擊 **Deployments** 標籤（側邊欄，左側）以查看當前部署的模型。
+1. 如果你想要的模型尚未部署，使用 **Create new deployment** 來部署它。
+1. 你將需要一個 _text-generation_ 模型 - 我們推薦: **gpt-35-turbo**
+1. 你將需要一個 _text-embedding_ 模型 - 我們推薦 **text-embedding-ada-002**
+
+現在更新環境變數以反映所使用的_部署名稱_。這通常與模型名稱相同，除非你明確更改了它。因此，作為範例，你可能會有:
+
+```bash
+AZURE_OPENAI_DEPLOYMENT='gpt-35-turbo'
+AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT='text-embedding-ada-002'
+```
+
+**不要忘記在完成後保存.env文件**。你現在可以退出文件並返回執行筆記本的說明。
+
+### 2.5 設定 OpenAI: 從 Profile
+
+你的 OpenAI API 金鑰可以在你的 [OpenAI 帳戶](https://platform.openai.com/api-keys?WT.mc_id=academic-105485-koreyst)中找到。如果你沒有，你可以註冊一個帳戶並建立一個 API 金鑰。一旦你有了金鑰，你可以用它來填充 `.env` 檔案中的 `OPENAI_API_KEY` 變數。
+
+### 2.6 設定 Hugging Face: 從個人資料
+
+您的 Hugging Face token 可以在您的個人資料中的[Access Tokens](https://huggingface.co/settings/tokens?WT.mc_id=academic-105485-koreyst)找到。不要公開張貼或分享這些資訊。相反地，為此專案使用建立一個新的 token，並將其複製到 `.env` 檔案中的 `HUGGING_FACE_API_KEY` 變數下。_注意:_ 這在技術上不是 API key，但用於身份驗證，因此我們保持這個命名慣例以保持一致性。
+