• 用法

  >>> from underthesea import sent_tokenize
  >>> text = 'Taylor cho biết lúc đầu cô cảm thấy ngại với cô bạn thân Amanda nhưng rồi mọi thứ trôi qua nhanh chóng. Amanda cũng thoải mái với mối quan hệ này.'
  
  >>> sent_tokenize(text)
  [
    "Taylor cho biết lúc đầu cô cảm thấy ngại với cô bạn thân Amanda nhưng rồi mọi thứ trôi qua nhanh chóng.",
    "Amanda cũng thoải mái với mối quan hệ này."
  ]
  

• 用法

  >>> from underthesea import text_normalize
  >>> text_normalize("Ðảm baỏ chất lựơng phòng thí nghịêm hoá học")
  "Đảm bảo chất lượng phòng thí nghiệm hóa học"
  

• 地址转换 (Address Conversion)

  >>> from underthesea import convert_address
  >>> result = convert_address("Phường Phúc Xá, Quận Ba Đình, Thành phố Hà Nội")
  >>> result.converted
  "Phường Hồng Hà, Thành phố Hà Nội"
  >>> result.mapping_type
  <MappingType.MERGED: 'merged'>
  

• 支持缩写

  >>> result = convert_address("P. Phúc Xá, Q. Ba Đình, TP. Hà Nội")
  >>> result.converted
  "Phường Hồng Hà, Thành phố Hà Nội"
  

• 分词 (Word Segmentation)

  >>> from underthesea import word_tokenize
  >>> word_tokenize("Chàng trai 9X Quảng Trị khởi nghiệp từ nấm sò")
  ["Chàng trai", "9X", "Quảng Trị", "khởi nghiệp", "từ", "nấm", "sò"]
  
  >>> word_tokenize("Chàng trai 9X Quảng Trị khởi nghiệp từ nấm sò", format="text")
  "Chàng_trai 9X Quảng_Trị khởi_nghiệp từ nấm sò"
  

• 词性标注 (POS tagging)

  >>> from underthesea import pos_tag
  >>> pos_tag('Chợ thịt chó nổi tiếng ở Sài Gòn bị truy quét')
  [('Chợ', 'N'),
   ('thịt', 'N'),
   ('chó', 'N'),
   ('nổi tiếng', 'A'),
   ('ở', 'E'),
   ('Sài Gòn', 'Np'),
   ('bị', 'V'),
   ('truy quét', 'V')]
  

• 块抽取 (chunking)

  >>> from underthesea import chunk
  >>> chunk('Bác sĩ bây giờ có thể thản nhiên báo tin bệnh nhân bị ung thư?')
  [('Bác sĩ', 'N', 'B-NP'),
   ('bây giờ', 'P', 'B-NP'),
   ('có thể', 'R', 'O'),
   ('thản nhiên', 'A', 'B-AP'),
   ('báo', 'V', 'B-VP'),
   ('tin', 'N', 'B-NP'),
   ('bệnh nhân', 'N', 'B-NP'),
   ('bị', 'V', 'B-VP'),
   ('ung thư', 'N', 'B-NP'),
   ('?', 'CH', 'O')]
  

• 依存句法分析 (dependency parsing)

  $ pip install underthesea[deep]
  

  >>> from underthesea import dependency_parse
  >>> dependency_parse('Tối 29/11, Việt Nam thêm 2 ca mắc Covid-19')
  [('Tối', 5, 'obl:tmod'),
   ('29/11', 1, 'flat:date'),
   (',', 1, 'punct'),
   ('Việt Nam', 5, 'nsubj'),
   ('thêm', 0, 'root'),
   ('2', 7, 'nummod'),
   ('ca', 5, 'obj'),
   ('mắc', 7, 'nmod'),
   ('Covid-19', 8, 'nummod')]
  

• 用法

  >>> from underthesea import ner
  >>> text = 'Chưa tiết lộ lịch trình tới Việt Nam của Tổng thống Mỹ Donald Trump'
  >>> ner(text)
  [('Chưa', 'R', 'O', 'O'),
   ('tiết lộ', 'V', 'B-VP', 'O'),
   ('lịch trình', 'V', 'B-VP', 'O'),
   ('tới', 'E', 'B-PP', 'O'),
   ('Việt Nam', 'Np', 'B-NP', 'B-LOC'),
   ('của', 'E', 'B-PP', 'O'),
   ('Tổng thống', 'N', 'B-NP', 'O'),
   ('Mỹ', 'Np', 'B-NP', 'B-LOC'),
   ('Donald', 'Np', 'B-NP', 'B-PER'),
   ('Trump', 'Np', 'B-NP', 'I-PER')]
  

• 深度学习模型 (Deep Learning Model)

  $ pip install underthesea[deep]
  

  >>> from underthesea import ner
  >>> text = "Bộ Công Thương xóa một tổng cục, giảm nhiều đầu mối"
  >>> ner(text, deep=True)
  [
    {'entity': 'B-ORG', 'word': 'Bộ'},
    {'entity': 'I-ORG', 'word': 'Công'},
    {'entity': 'I-ORG', 'word': 'Thương'}
  ]
  

• 文本分类 (Text Classification)

  >>> from underthesea import classify
  
  >>> classify('HLV đầu tiên ở Premier League bị sa thải sau 4 vòng đấu')
  ['The thao']
  
  >>> classify('Hội đồng tư vấn kinh doanh Asean vinh danh giải thưởng quốc tế')
  ['Kinh doanh']
  
  >> classify('Lãi suất từ BIDV rất ưu đãi', domain='bank')
  ['INTEREST_RATE']
  

• 情感分析 (Sentiment Analysis)

  >>> from underthesea import sentiment
  
  >>> sentiment('hàng kém chất lg,chăn đắp lên dính lông lá khắp người. thất vọng')
  'negative'
  >>> sentiment('Sản phẩm hơi nhỏ so với tưởng tượng nhưng chất lượng tốt, đóng gói cẩn thận.')
  'positive'
  
  >>> sentiment('Đky qua đường link ở bài viết này từ thứ 6 mà giờ chưa thấy ai lhe hết', domain='bank')
  ['CUSTOMER_SUPPORT#negative']
  >>> sentiment('Xem lại vẫn thấy xúc động và tự hào về BIDV của mình', domain='bank')
  ['TRADEMARK#positive']
  

• 基于提示的分类 (Prompt-based Classification)

  $ pip install underthesea[prompt]
  $ export OPENAI_API_KEY=YOUR_KEY
  

  >>> from underthesea import classify
  >>> classify("HLV ngoại đòi gần tỷ mỗi tháng dẫn dắt tuyển Việt Nam", model='prompt')
  Thể thao
  

Lang Detect 应用程序接口 (API)。由 FastText 语言识别模型提供支持，通过 underthesea_core 使用纯 Rust 进行推理。

脚本中的用法示例

```python
>>> from underthesea import lang_detect

>>> lang_detect("Cựu binh Mỹ trả nhật ký nhẹ lòng khi thấy cuộc sống hòa bình tại Việt Nam")
vi
```

• 深度学习模型 (Deep Learning Model)

  $ pip install underthesea[deep]
  

  >>> from underthesea import translate
  
  >>> translate("Hà Nội là thủ đô của Việt Nam")
  'Hanoi is the capital of Vietnam'
  
  >>> translate("Ẩm thực Việt Nam nổi tiếng trên thế giới")
  'Vietnamese cuisine is famous around the world'
  
  >>> translate("I love Vietnamese food", source_lang='en', target_lang='vi')
  'Tôi yêu ẩm thực Việt Nam'
  

文本转语音 API。感谢 NTT123/vietTTS 的出色工作

安装扩展依赖和模型

```bash
$ pip install "underthesea[voice]"
$ underthesea download-model VIET_TTS_V0_4_1
```

脚本中的使用示例

```python
>>> from underthesea.pipeline.tts import tts

>>> tts("Cựu binh Mỹ trả nhật ký nhẹ lòng khi thấy cuộc sống hòa bình tại Việt Nam")
A new audio file named `sound.wav` will be generated.
```

命令行中的使用示例

```sh
$ underthesea tts "Cựu binh Mỹ trả nhật ký nhẹ lòng khi thấy cuộc sống hòa bình tại Việt Nam"
```

支持 OpenAI 和 Azure OpenAI 的对话式 AI 智能体。

安装扩展依赖

```bash
$ pip install "underthesea[agent]"
$ export OPENAI_API_KEY=your_api_key
# Or for Azure OpenAI:
# export AZURE_OPENAI_API_KEY=your_key
# export AZURE_OPENAI_ENDPOINT=https://xxx.openai.azure.com
```

脚本中的使用示例

```python
>>> from underthesea import agent

>>> agent("Xin chào!")
'Xin chào! Tôi có thể giúp gì cho bạn?'

>>> agent("NLP là gì?")
'NLP (Natural Language Processing) là xử lý ngôn ngữ tự nhiên...'

>>> agent("Cho ví dụ về word tokenization tiếng Việt")
'Word tokenization trong tiếng Việt là quá trình...'

# Reset conversation
>>> agent.reset()
```

支持 Azure OpenAI

```python
>>> agent("Hello", provider="azure", model="my-gpt4-deployment")
```

带自定义工具的 Agent（函数调用）

```python
>>> from underthesea.agent import Agent, Tool

# Define tools as functions
>>> def get_weather(location: str) -> dict:
...     """Get current weather for a location."""
...     return {"location": location, "temp": 25, "condition": "sunny"}

>>> def search_news(query: str) -> str:
...     """Search Vietnamese news."""
...     return f"Results for: {query}"

# Create agent with tools
>>> my_agent = Agent(
...     name="assistant",
...     tools=[
...         Tool(get_weather, description="Get weather for a city"),
...         Tool(search_news, description="Search Vietnamese news"),
...     ],
...     instruction="You are a helpful Vietnamese assistant."
... )

# Agent automatically calls tools when needed
>>> my_agent("Thời tiết ở Hà Nội thế nào?")
'Thời tiết ở Hà Nội hiện tại là 25°C và nắng.'

>>> my_agent.reset()  # Clear conversation history
```

使用默认工具（如 LangChain/OpenAI 工具）

```python
>>> from underthesea.agent import Agent, default_tools

# Create agent with built-in tools:
# calculator, datetime, web_search, wikipedia, shell, python, file ops...
>>> my_agent = Agent(
...     name="assistant",
...     tools=default_tools,
... )

>>> my_agent("What time is it?")           # Uses datetime tool
>>> my_agent("Calculate sqrt(144) + 10")   # Uses calculator tool
>>> my_agent("Search for Python tutorials") # Uses web_search tool
```

列出资源

$ underthesea list-data
| Name                      | Type        | License | Year | Directory                          |
|---------------------------+-------------+---------+------+------------------------------------|
| CP_Vietnamese_VLC_v2_2022 | Plaintext   | Open    | 2023 | datasets/CP_Vietnamese_VLC_v2_2022 |
| UIT_ABSA_RESTAURANT       | Sentiment   | Open    | 2021 | datasets/UIT_ABSA_RESTAURANT       |
| UIT_ABSA_HOTEL            | Sentiment   | Open    | 2021 | datasets/UIT_ABSA_HOTEL            |
| SE_Vietnamese-UBS         | Sentiment   | Open    | 2020 | datasets/SE_Vietnamese-UBS         |
| CP_Vietnamese-UNC         | Plaintext   | Open    | 2020 | datasets/CP_Vietnamese-UNC         |
| DI_Vietnamese-UVD         | Dictionary  | Open    | 2020 | datasets/DI_Vietnamese-UVD         |
| UTS2017-BANK              | Categorized | Open    | 2017 | datasets/UTS2017-BANK              |
| VNTQ_SMALL                | Plaintext   | Open    | 2012 | datasets/LTA                       |
| VNTQ_BIG                  | Plaintext   | Open    | 2012 | datasets/LTA                       |
| VNESES                    | Plaintext   | Open    | 2012 | datasets/LTA                       |
| VNTC                      | Categorized | Open    | 2007 | datasets/VNTC                      |

$ underthesea list-data --all

下载资源

$ underthesea download-data CP_Vietnamese_VLC_v2_2022
Resource CP_Vietnamese_VLC_v2_2022 is downloaded in ~/.underthesea/datasets/CP_Vietnamese_VLC_v2_2022 folder