[TRANSLATION] Initial version for vietnamese

.github/workflows/build_pr_documentation.yml

@@ -17,4 +17,4 @@ jobs:
       package_name: agents-course
       path_to_docs: agents-course/units/
       additional_args: --not_python_module
-      languages: en
+      languages: en vi

scripts/vi-translation.py

@@ -0,0 +1,148 @@
+import os
+import sys
+import re
+from huggingface_hub import InferenceClient
+
+PROMPT = lambda content: f'''
+You are a translator for the Vietnamese translation team. You are tasked with translating the following text into Vietnamese. You must follow these instructions:
+- Translate the text into Vietnamese, while keeping the original formatting (either Markdown, MDX or HTML)
+- Inside code blocks, translate the comments but leave the code as-is ; If the code block contains quite plain texts, you MUST provide the translation in <details> tag.
+- Do not translate inline code, the URLs and file paths
+- If the term is abbreviated, keep the original term and provide the translation in parentheses for the first time it appears in the text.
+- If there are any slag or funny joke in english, keep it (do not translate) and give an explanation so vietnamese reader can understand.
+- Use "ta", "chúng ta", "chúng mình", "các bạn" as pronouns.
+
+KEEP THESE TERMS (DO NOT TRANSLATE, do NOT add translation in parentheses): model, API, SDK, CLI, HTML, GGUF, AI, training, inference, server, client, notebook, python, Hugging Face, transformers, diffusion, diffuser, data, function, LangGraph, LangChain, Llama, Gemma, token, Unit, pretrain, Live (live stream), form, format, certificate, Space, CodeAgent
+
+Also KEEP these terms but PROVIDE TRANSLATION in parentheses for the first time it appears in the text: alignment (cân chỉnh), LLM, RAG (Tìm kiếm và tạo ra câu trả lời), Agent (tác nhân), Tools (công cụ), "Special Token" (Token đặc biệt), "chain-of-thought" (luồng suy luận), fine-tuning (tinh chỉnh), Thought-Action-Observation
+
+For these terms, use the pre-defined translation:
+- Quick Quiz: Kiểm tra nhanh
+- Unit: Chương
+- Bonus Unit: Chương bổ trợ
+- Module: Mô-đun
+- Lesson ...: Bài ...
+- Course: Khóa học
+- state-of-the-art: nổi tiếng
+- Q&A: Hỏi và Đáp
+- Dummy: ảo (or "giả", or "thử" depending on the context)
+- onboarding: làm quen
+- Hands-on: Thực hành
+- Challenge: Bài tập lớn
+
+Here is an example:
+- Original text: To run the models, we will use [ollama](https://ollama.com), a command line tool that allows you to run LLMs and embedding models from Hugging Face. With ollama, you **don't need** to have access to a server or cloud service to run the models. You can run the models directly **on your computer**.
+- Translation: Để chạy các model, ta sẽ sử dụng [ollama](https://ollama.com), một công cụ dòng lệnh cho phép bạn chạy LLMs và embedding models từ Hugging Face. Với ollama, bạn **không cần** phải tạo server hay truy cập API bên thứ 3. Bạn có thể chạy các model trực tiếp **trên máy tính của bạn**.
+
+Here is another example:
+- Original text: The model can then be **aligned** to the creator's preferences. For instance, a customer service chat model that must never be impolite to customers.
+- Translation: Model sau đó có thể được **alignment** (cân chỉnh) theo mong muốn của người tạo. Ví dụ: model chat hỗ trợ khách hàng không bao giờ được bất lịch sự.
+
+If the code block contains many plain texts, prove translation in collapsible <details> tag. Example:
+- Original text:
+    ```
+    <|im_start|>Hello, how are you?<|im_end|>
+    <|im_start|>I'm fine, thank you.<|im_end|>
+    message = {{"user": "This is a test"}}
+    ```
+- Translation (add the <details> collapsible ABOVE of the original code block):
+    <details>
+    <summary>Bấm để xem bản dịch tiếng Việt</summary>
+    ```
+    <|im_start|>Xin chào, bạn có khỏe không?<|im_end|>
+    <|im_start|>Mình khỏe, cảm ơn bạn.<|im_end|>
+    message = {{"user": "Đây là một tin nhắn thử"}}
+    ```
+    </details>
+    ```
+    <|im_start|>Hello, how are you?<|im_end|>
+    <|im_start|>I'm fine, thank you.<|im_end|>
+    message = {{"user": "This is a test"}}
+    ```
+
+
+IMPORTANT: Only output the translated text and nothing else, no need explaination or instruction. The input text is between "=== BEGIN OF TEXT ===" and "=== END OF TEXT ===".
+
+Please translate the following text to vietnamese:
+
+=== BEGIN OF TEXT ===
+{content}
+=== END OF TEXT ===
+'''.strip()
+
+# Get the directory containing the current script
+script_dir = os.path.dirname(os.path.abspath(__file__))
+inp_dir = os.path.join(script_dir, '..', 'units/en')
+get_our_path = lambda x: x.replace('/en', '/vi')
+model = "deepseek-ai/DeepSeek-R1"
+client = InferenceClient(
+	provider="together",
+    # api_key is read from the environment
+)
+
+def auto_translate(
+    inp_dir: str,
+    get_our_path: callable,
+    model: str,
+    client: InferenceClient,
+    PROMPT: callable
+):
+    escape_special_tokens = lambda x: x.replace('<think>', '<%%think%%>').replace('</think>', '<%%/think%%>')
+    unescape_special_tokens = lambda x: x.replace('<%%think%%>', '<think>').replace('<%%/think%%>', '</think>')
+
+    # Get the list of all files in the directory, recursively
+    inp_files: list[str] = []
+    print('Collecting files...')
+    for root, dirs, files in os.walk(inp_dir):
+        for file in files:
+            if file.endswith('.mdx') or file == "_toctree.yml":
+                fname = os.path.join(root, file)
+                print('  +', fname)
+                inp_files.append(fname)
+
+    def write_out_file(fpath: str, content: str):
+        base_path = os.path.dirname(fpath)
+        os.makedirs(base_path, exist_ok=True)
+        with open(fpath, 'w', encoding='utf-8') as f:
+            f.write(content)
+
+    # Read the content of the file and process
+    for i, inp_file in enumerate(inp_files):
+        out_file = get_our_path(inp_file)
+        if os.path.exists(out_file):
+            print(f'[{i+1}/{len(inp_files)}] Skipping file: {inp_file}')
+            continue
+        with open(inp_file, 'r', encoding='utf-8') as f:
+            content: str = f.read()
+            content = escape_special_tokens(content)
+            if content.strip() == "":
+                print(f'[{i+1}/{len(inp_files)}] Skipping empty file: {inp_file}')
+                write_out_file(out_file, "")
+                continue
+
+            print(f'[{i+1}/{len(inp_files)}] Processing file: {inp_file}')
+            stream = client.chat.completions.create(
+                model=model,
+                temperature=0.0,
+                messages=[
+                    {"role": "user", "content": PROMPT(content)},
+                ],
+                stream=True,
+            )
+            final_text = ""
+            for chunk in stream:
+                print(chunk.choices[0].delta.content, end="")
+                sys.stdout.flush()
+                final_text += chunk.choices[0].delta.content
+            # Optionally filter <think>...</think> reasoning process
+            final_text = final_text.split('</think>').pop().strip()
+            # Write the output to the file
+            final_text = unescape_special_tokens(final_text)
+            write_out_file(out_file, final_text)
+            print()
+            print(f'  -> Translated to: {out_file}')
+            print("--" * 20)
+            #break
+
+if __name__ == '__main__':
+    auto_translate(inp_dir, get_our_path, model, client, PROMPT)

units/vi/_toctree.yml

@@ -0,0 +1,58 @@
+- title: Chương 0. Welcome to the course
+  sections:
+  - local: unit0/introduction
+    title: Chào mừng bạn đến với khóa học 🤗
+  - local: unit0/onboarding
+    title: Làm quen
+  - local: unit0/discord101
+    title: (Bổ trợ) Discord 101 (Giới thiệu cơ bản về Discord)
+- title: Live 1. Cách khóa học vận hành và Hỏi và Đáp
+  sections:
+  - local: communication/live1
+    title: Live 1. Cách khóa học vận hành và Hỏi và Đáp
+- title: Chương 1. Giới thiệu về Agents
+  sections:
+  - local: unit1/introduction
+    title: Giới thiệu
+  - local: unit1/what-are-agents
+    title: Agent là gì?
+  - local: unit1/quiz1
+    title: Kiểm tra nhanh 1
+  - local: unit1/what-are-llms
+    title: LLM là gì?
+  - local: unit1/messages-and-special-tokens
+    title: Tin nhắn và Special Token
+  - local: unit1/tools
+    title: Tools là gì?
+  - local: unit1/quiz2
+    title: Kiểm tra nhanh 2
+  - local: unit1/agent-steps-and-structure
+    title: Hiểu về AI Agents qua chu kỳ Thought-Action-Observation
+  - local: unit1/thoughts
+    title: Suy nghĩ, Lập luận nội bộ và Phương pháp Re-Act
+  - local: unit1/actions
+    title: Hành động, Giúp Agent tương tác với môi trường
+  - local: unit1/observations
+    title: Quan sát, Tích hợp phản hồi để điều chỉnh
+  - local: unit1/dummy-agent-library
+    title: Thư viện Dummy Agent
+  - local: unit1/tutorial
+    title: Hãy tạo Agent đầu tiên với Smolagents
+  - local: unit1/final-quiz
+    title: Bài kiểm tra cuối Chương 1
+  - local: unit1/conclusion
+    title: Kết luận
+- title: Chương Bổ Trợ 1. Tinh chỉnh LLM cho Function-calling
+  sections:
+  - local: bonus-unit1/introduction
+    title: Giới thiệu
+  - local: bonus-unit1/what-is-function-calling
+    title: Function Calling là gì?
+  - local: bonus-unit1/fine-tuning
+    title: Hãy fine-tuning model cho Function-calling
+  - local: bonus-unit1/conclusion
+    title: Kết luận
+- title: Khi nào các bước tiếp theo được công bố?
+  sections:
+  - local: communication/next-units
+    title: Các Chương tiếp theo

units/vi/bonus-unit1/conclusion.mdx

@@ -0,0 +1,13 @@
+# Kết luận [[conclusion]]
+
+Chúc mừng các bạn đã hoàn thành Chương Bổ Trợ đầu tiên 🥳
+
+Bạn đã **thành thạo việc hiểu function-calling và cách fine-tune (tinh chỉnh) model để thực hiện function-calling**!
+
+Nếu có một lời khuyên từ chúng mình lúc này, đó là hãy thử **fine-tune các model khác nhau**. **Cách học tốt nhất chính là thực hành.**
+
+Ở Chương tiếp theo, các bạn sẽ học cách sử dụng **các framework nổi tiếng như `smolagents`, `LlamaIndex` và `LangGraph`**.
+
+Cuối cùng, chúng mình rất muốn **nghe ý kiến của bạn về khóa học và cách cải thiện nó**. Nếu có phản hồi, hãy 👉 [điền vào form này](https://docs.google.com/forms/d/e/1FAIpQLSe9VaONn0eglax0uTwi29rIn4tM7H2sYmmybmG5jJNlE5v0xA/viewform?usp=dialog)
+
+### Hãy tiếp tục không ngừng học hỏi!! 🤗

units/vi/bonus-unit1/fine-tuning.mdx

@@ -0,0 +1,47 @@
+# Hãy Fine-Tune Model của Bạn cho Chức năng Gọi Hàm
+
+Chúng ta đã sẵn sàng để fine-tune (tinh chỉnh) model đầu tiên cho function-calling rồi đây 🔥.
+
+## Làm thế nào để training model cho function-calling?
+
+> Câu trả lời: Ta cần **data**
+
+Quá trình training model có thể chia thành 3 bước:
+
+1. **Model được pretrain trên lượng data khổng lồ**. Kết quả của bước này là **pretrained model**. Ví dụ: [google/gemma-2-2b](https://huggingface.co/google/gemma-2-2b). Đây là model nền tảng và chỉ biết **dự đoán token tiếp theo mà không có khả năng tuân theo chỉ dẫn**.
+
+2. Để hữu ích trong bối cảnh chat, model cần được **fine-tune** để tuân theo hướng dẫn. Ở bước này, quá trình training có thể được thực hiện bởi nhà phát triển model, cộng đồng mã nguồn mở, bạn hay bất kỳ ai. Ví dụ: [google/gemma-2-2b-it](https://huggingface.co/google/gemma-2-2b-it) là model đã được fine-tune để tuân theo chỉ dẫn bởi đội ngũ Google của dự án Gemma.
+
+3. Model sau đó có thể được **alignment** (cân chỉnh) theo mong muốn của người tạo. Ví dụ: model chat hỗ trợ khách hàng không bao giờ được bất lịch sự.
+
+Thông thường các sản phẩm hoàn chỉnh như Gemini hay Mistral **sẽ trải qua cả 3 bước**, trong khi các model bạn tìm thấy trên Hugging Face đã hoàn thành một hoặc nhiều bước training.
+
+Trong hướng dẫn này, chúng ta sẽ xây dựng model function-calling dựa trên [google/gemma-2-2b-it](https://huggingface.co/google/gemma-2-2b-it). Ta chọn model đã fine-tune [google/gemma-2-2b-it](https://huggingface.co/google/gemma-2-2b-it) thay vì model nền tảng [google/gemma-2-2b](https://huggingface.co/google/gemma-2-2b) vì model đã fine-tune đã được cải thiện cho use-case của ta.
+
+Nếu bắt đầu từ pretrained model **sẽ cần training nhiều hơn để học cách tuân theo chỉ dẫn, chat VÀ function-calling**.
+
+Bằng cách bắt đầu từ model đã fine-tune để tuân theo chỉ dẫn, **ta giảm thiểu lượng thông tin model cần học**.
+
+## LoRA (Low-Rank Adaptation of Large Language Models - Thích ứng Hạng thấp cho Mô hình Ngôn ngữ Lớn)
+
+LoRA là kỹ thuật training nhẹ và phổ biến giúp **giảm đáng kể số parameters cần training**.
+
+Nó hoạt động bằng cách **chèn một lượng nhỏ weights mới vào model như adapter để training**. Điều này giúp training với LoRA nhanh hơn, tiết kiệm bộ nhớ hơn, và tạo ra weights model nhỏ hơn (vài trăm MB), dễ lưu trữ và chia sẻ.
+
+<img src="https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/unit1/blog_multi-lora-serving_LoRA.gif" alt="LoRA inference" width="50%"/>
+
+LoRA hoạt động bằng cách thêm các cặp ma trận phân tách hạng vào các lớp Transformer, thường tập trung vào các lớp tuyến tính. Trong quá trình training, ta sẽ "đóng băng" phần còn lại của model và chỉ cập nhật weights của các adapter mới này.
+
+Nhờ vậy, số **parameters** cần training giảm đáng kể vì ta chỉ cần cập nhật weights của adapter.
+
+Trong quá trình inference, đầu vào sẽ đi qua adapter và model nền tảng, hoặc các weights adapter có thể được hợp nhất với model nền tảng mà không gây thêm độ trễ.
+
+LoRA đặc biệt hữu ích để điều chỉnh các mô hình ngôn ngữ **lớn** cho các tác vụ hoặc lĩnh vực cụ thể trong khi vẫn quản lý được yêu cầu tài nguyên. Điều này giúp giảm bộ nhớ **required** để training model.
+
+Nếu muốn tìm hiểu thêm về cách hoạt động của LoRA, hãy xem [hướng dẫn này](https://huggingface.co/learn/nlp-course/chapter11/4?fw=pt).
+
+## Fine-Tuning (tinh chỉnh) Model cho Function-Calling
+
+Bạn có thể truy cập notebook hướng dẫn tại đây 👉 [đây](https://huggingface.co/agents-course/notebooks/blob/main/bonus-unit1/bonus-unit1.ipynb).
+
+Sau đó, click vào [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/#fileId=https://huggingface.co/agents-course/notebooks/blob/main/bonus-unit1/bonus-unit1.ipynb) để chạy notebook trên Colab.

units/vi/bonus-unit1/introduction.mdx

@@ -0,0 +1,53 @@
+# Giới thiệu
+
+![Hình ảnh minh họa Chương Bổ Trợ 1](https://huggingface.co/datasets/agents-course/course-images/resolve/main/en/bonus-unit1/thumbnail.jpg)
+
+Chào mừng bạn đến với **Chương Bổ Trợ đầu tiên** này, nơi ta sẽ học cách **tinh chỉnh (fine-tuning) Mô hình Ngôn ngữ Lớn (LLM) cho function calling**.
+
+Với LLMs, function calling đang nhanh chóng trở thành kỹ thuật *phải-biết*. 
+
+Ý tưởng là thay vì chỉ dựa vào phương pháp prompt-based như trong Chương 1, function calling sẽ huấn luyện model của bạn **thực hiện hành động và diễn giải quan sát trong giai đoạn training**, giúp AI trở nên mạnh mẽ hơn.
+
+> **Khi nào nên học Chương Bổ Trợ này?**
+>
+> Phần này **không bắt buộc** và nâng cao hơn Chương 1. Bạn có thể học ngay hoặc quay lại sau khi nâng cao kiến thức nhờ khóa học.
+>  
+> Đừng lo, Chương Bổ Trợ được thiết kế để cung cấp đầy đủ thông tin cần thiết. Chúng mình sẽ hướng dẫn bạn từng khái niệm cốt lõi về tinh chỉnh model cho function calling dù bạn chưa hiểu sâu về fine-tuning.
+
+Để học tốt Chương Bổ Trợ này, bạn cần:
+
+1. Biết cách Tinh chỉnh LLM với Transformers. Nếu chưa biết, [xem tại đây](https://huggingface.co/learn/nlp-course/chapter3/1?fw=pt).
+
+2. Biết dùng `SFTTrainer` để tinh chỉnh model. Tìm hiểu thêm tại [tài liệu này](https://huggingface.co/learn/nlp-course/en/chapter11/1). 
+
+---
+
+## Nội dung học
+
+1. **Function Calling**  
+   Cách LLMs hiện đại tổ chức hội thoại hiệu quả để kích hoạt **Tools (công cụ)**.
+
+2. **LoRA (Low-Rank Adaptation)**  
+   Phương pháp tinh chỉnh **nhẹ và hiệu quả** giúp giảm chi phí tính toán và lưu trữ. LoRA giúp huấn luyện model lớn *nhanh hơn, rẻ hơn, dễ triển khai hơn*.
+
+3. **Chu trình Suy nghĩ → Hành động → Quan sát** trong model Function Calling  
+   Cách tiếp cận đơn giản nhưng mạnh mẽ để model quyết định khi nào (và cách nào) gọi function, theo dõi các bước trung gian, và diễn giải kết quả từ Tools/API bên ngoài.
+
+4. **Token Đặc biệt Mới**  
+   Chúng ta sẽ giới thiệu **các marker đặc biệt** giúp model phân biệt:
+   - Lý luận nội bộ kiểu "chain-of-thought" (luồng suy luận)  
+   - Lệnh gọi function  
+   - Phản hồi từ công cụ bên ngoài
+
+---
+
+Kết thúc Chương Bổ Trợ này, bạn sẽ có thể:
+
+- **Hiểu** cách hoạt động nội bộ của APIs khi sử dụng Tools  
+- **Tinh chỉnh** model bằng kỹ thuật LoRA  
+- **Triển khai** và **tùy chỉnh** chu trình Thought → Act → Observe để tạo workflow Function-calling mạnh mẽ  
+- **Thiết kế và sử dụng** token đặc biệt để tách biệt lý luận nội bộ của model với hành động bên ngoài
+
+Và quan trọng nhất: **Bạn sẽ có model được tinh chỉnh để thực hiện function calling!** 🔥
+
+Cùng khám phá **function calling** thôi!