Skip to content

Commit

Permalink
Add zh-tw translations
Browse files Browse the repository at this point in the history
  • Loading branch information
doggy8088 committed Jul 2, 2024
1 parent c883184 commit a483db6
Show file tree
Hide file tree
Showing 27 changed files with 5,276 additions and 1 deletion.
151 changes: 151 additions & 0 deletions 00-course-setup/translations/tw/README.md
Original file line number Diff line number Diff line change
@@ -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)

136 changes: 136 additions & 0 deletions 00-course-setup/translations/tw/SETUP.md
Original file line number Diff line number Diff line change
@@ -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,但用於身份驗證,因此我們保持這個命名慣例以保持一致性。

Loading

0 comments on commit a483db6

Please sign in to comment.