# Serve CLI

CLI `transformers serve` là một lựa chọn nhẹ nhàng cho các máy chủ cục bộ hoặc tự lưu trữ. Nó tránh được chi phí thời gian chạy và vận hành bổ sung của các bộ máy suy luận chuyên dụng như vLLM. Hãy sử dụng nó cho việc đánh giá, thử nghiệm và triển khai với tải vừa phải. Các tính năng như [continuous batching](../continuous_batching) giúp tăng thông lượng và giảm độ trễ.

> [!TIP]
> Đối với triển khai sản xuất quy mô lớn, hãy sử dụng vLLM hoặc SGLang với một mô hình Transformer làm backend. Tìm hiểu thêm trong hướng dẫn [Các backend suy luận](../community_integrations/transformers_as_backend).

Lệnh `transformers serve` khởi tạo một máy chủ cục bộ tương thích với [OpenAI SDK](https://platform.openai.com/docs/overview). Máy chủ này hoạt động với nhiều ứng dụng bên thứ ba và hỗ trợ các API REST bên dưới.

- `/v1/chat/completions` cho các yêu cầu văn bản, hình ảnh, âm thanh và video
- `/v1/completions` cho các hoàn thành văn bản cũ từ một prompt tự do
- `/v1/responses` hỗ trợ [Responses API](https://platform.openai.com/docs/api-reference/responses)
- `/v1/audio/transcriptions` cho việc chuyển đổi âm thanh thành văn bản
- `/v1/systemone` trả lời các câu hỏi có dạng (lựa chọn, điểm số, có/không) với một xác suất cho mỗi câu trả lời được phép
- `/v1/models` liệt kê các model khả dụng cho các tích hợp bên thứ ba
- `/load_model` truyền tiến trình tải mô hình qua SSE

Cài đặt các phụ thuộc phục vụ.

```bash
pip install transformers[serving]
```

Chạy `transformers serve` để khởi động máy chủ. Địa chỉ máy chủ mặc định là http://localhost:8000.

```shell
transformers serve
```

## v1/chat/completions

API `v1/chat/completions` được xây dựng dựa trên [Chat Completions API](https://platform.openai.com/docs/api-reference/chat). Nó hỗ trợ các yêu cầu văn bản, hình ảnh, âm thanh và video cho LLM, VLM và các mô hình đa phương thức. Hãy sử dụng nó với `curl`, [InferenceClient](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/inference_client#huggingface_hub.InferenceClient) hoặc client [OpenAI](https://platform.openai.com/docs/quickstart).

### Hoàn thành dựa trên văn bản

```python
from huggingface_hub import InferenceClient

messages = [{"role": "user", "content": "What is the Transformers library known for?"}]
client = InferenceClient("http://localhost:8000")

result = client.chat_completion(messages, model="Qwen/Qwen2.5-0.5B-Instruct", max_tokens=256)
print(result.choices[0].message.content)
```

[InferenceClient](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/inference_client#huggingface_hub.InferenceClient) trả về một chuỗi đã được in ra.

```shell
The Transformers library is primarily known for its ability to create and manipulate large-scale language models [...]
```

```python
from huggingface_hub import InferenceClient

messages = [{"role": "user", "content": "What is the Transformers library known for?"}]
client = InferenceClient("http://localhost:8000")

stream = client.chat_completion(messages, model="Qwen/Qwen2.5-0.5B-Instruct", max_tokens=256, stream=True)
for chunk in stream:
    token = chunk.choices[0].delta.content
    if token:
        print(token, end="")
```

[InferenceClient](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/inference_client#huggingface_hub.InferenceClient) trả về một chuỗi đã được in ra.

```shell
The Transformers library is primarily known for its ability to create and manipulate large-scale language models [...]
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

completion = client.chat.completions.create(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    messages=[
        {
            "role": "user",
            "content": "What is the Transformers library known for?"
        }
    ],
)
print(completion.choices[0].message.content)
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```shell
The Transformers library is primarily known for its ability to create and manipulate large-scale language models [...]
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

completion = client.chat.completions.create(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    messages=[
        {
            "role": "user",
            "content": "What is the Transformers library known for?"
        }
    ],
    stream=True,
)

for chunk in completion:
    token = chunk.choices[0].delta.content
    if token:
        print(token, end="")
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```shell
The Transformers library is primarily known for its ability to create and manipulate large-scale language models [...]
```

```shell
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "messages": [{"role": "user", "content": "What is the Transformers library known for?"}],
    "temperature": 0.9,
    "max_tokens": 256
  }'
```

Lệnh trả về một chuỗi JSON.

```json
{
  "id": "ade3578d-e2c3-47ed-b651-c014991a92f6",
  "choices": [
    {
      "finish_reason": "length",
      "index": 0,
      "message": {
        "content": "The Transformers library is primarily known for its ability to create and manipulate large-scale language models [...]",
        "role": "assistant"
      }
    }
  ],
  "created": 1776184004,
  "model": "Qwen/Qwen2.5-0.5B-Instruct@main",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 256,
    "prompt_tokens": 37,
    "total_tokens": 293
  }
}
```

```shell
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "messages": [{"role": "user", "content": "What is the Transformers library known for?"}],
    "temperature": 0.9,
    "max_tokens": 256,
    "stream": true
  }'
```

Lệnh trả về một luồng các khối dữ liệu.

```shell
data: {"id":"596d3941-754d-43b4-8773-9bf9940049f5","choices":[{"delta":{"role":"assistant"},"index":0}],"created":1776183469,"model":"Qwen/Qwen2.5-0.5B-Instruct@main","object":"chat.completion.chunk","system_fingerprint":""}

data: {"id":"596d3941-754d-43b4-8773-9bf9940049f5","choices":[{"delta":{"content":"The"},"index":0}],"created":1776183469,"model":"Qwen/Qwen2.5-0.5B-Instruct@main","object":"chat.completion.chunk","system_fingerprint":""}

(...)
```

### Hoàn thành dựa trên hình ảnh

```python
from huggingface_hub import InferenceClient

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg",
                }
            },
        ],
    }
]
client = InferenceClient("http://localhost:8000")

result = client.chat_completion(messages, model="Qwen/Qwen2.5-VL-7B-Instruct", max_tokens=256)
print(result.choices[0].message.content)
```

[InferenceClient](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/inference_client#huggingface_hub.InferenceClient) trả về một chuỗi đã được in ra.

```xmp
The image depicts an astronaut in a space suit standing on what appears to be the surface of the moon, given the barren, rocky landscape and the dark sky in the background. The astronaut is holding a large egg that has cracked open, revealing a small creature inside. The scene is imaginative and playful, combining elements of space exploration with a whimsical twist involving the egg and the creature.
```

```python
from huggingface_hub import InferenceClient

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {
                "type": "image_url",
                "image_url": {
                    "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg",
                }
            },
        ],
    }
]
client = InferenceClient("http://localhost:8000")

stream = client.chat_completion(messages, model="Qwen/Qwen2.5-VL-7B-Instruct", max_tokens=256, stream=True)
for chunk in stream:
    token = chunk.choices[0].delta.content
    if token:
        print(token, end="")
```

[InferenceClient](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/inference_client#huggingface_hub.InferenceClient) trả về một chuỗi đã được in ra.

```xmp
The image depicts an astronaut in a space suit standing on what appears to be the surface of the moon, given the barren, rocky landscape and the dark sky in the background. The astronaut is holding a large egg that has cracked open, revealing a small creature inside. The scene is imaginative and playful, combining elements of space exploration with a whimsical twist involving the egg and the creature.
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

completion = client.chat.completions.create(
    model="Qwen/Qwen2.5-VL-7B-Instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg",
                    }
                },
            ],
        }
    ],
)
print(completion.choices[0].message.content)
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```xmp
The image depicts an astronaut in a space suit standing on what appears to be the surface of the moon, given the barren, rocky landscape and the dark sky in the background. The astronaut is holding a large egg that has cracked open, revealing a small creature inside. The scene is imaginative and playful, combining elements of space exploration with a whimsical twist involving the egg and the creature.
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

completion = client.chat.completions.create(
    model="Qwen/Qwen2.5-VL-7B-Instruct",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What's in this image?"},
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg",
                    }
                },
            ],
        }
    ],
    stream=True,
)

for chunk in completion:
    token = chunk.choices[0].delta.content
    if token:
        print(token, end="")
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```xmp
The image depicts an astronaut in a space suit standing on what appears to be the surface of the moon, given the barren, rocky landscape and the dark sky in the background. The astronaut is holding a large egg that has cracked open, revealing a small creature inside. The scene is imaginative and playful, combining elements of space exploration with a whimsical twist involving the egg and the creature.
```

```shell
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-VL-7B-Instruct",
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What's in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
            }
          }
        ]
      }
    ],
    "max_tokens": 256
  }'
```

Lệnh trả về một chuỗi JSON.

```json
{
  "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "The image depicts an astronaut in a space suit standing on what appears to be the surface of the moon [...]",
        "role": "assistant"
      }
    }
  ],
  "created": 1753366665,
  "model": "Qwen/Qwen2.5-VL-7B-Instruct@main",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 50,
    "prompt_tokens": 120,
    "total_tokens": 170
  }
}
```

```shell
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-VL-7B-Instruct",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "type": "text",
            "text": "What's in this image?"
          },
          {
            "type": "image_url",
            "image_url": {
              "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"
            }
          }
        ]
      }
    ],
    "max_tokens": 256
  }'
```

Lệnh trả về một luồng các khối dữ liệu.

```shell
data: {"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","choices":[{"delta":{"role":"assistant"},"index":0}],"created":1753366665,"model":"Qwen/Qwen2.5-VL-7B-Instruct@main","object":"chat.completion.chunk","system_fingerprint":""}

data: {"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","choices":[{"delta":{"content":"The "},"index":0}],"created":1753366701,"model":"Qwen/Qwen2.5-VL-7B-Instruct@main","object":"chat.completion.chunk","system_fingerprint":""}

(...)
```

### Hoàn thành dựa trên âm thanh

Các mô hình đa phương thức như [Gemma 4](https://huggingface.co/google/gemma-4-E2B-it) và [Qwen2.5-Omni](https://huggingface.co/Qwen/Qwen2.5-Omni-3B) nhận đầu vào âm thanh thông qua kiểu nội dung `input_audio` của OpenAI. Hãy mã hóa Base64 âm thanh và chỉ định định dạng (`mp3` hoặc `wav`).

```python
import base64
from huggingface_hub.utils import httpx
from huggingface_hub import InferenceClient

audio_url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3"
audio_b64 = base64.b64encode(httpx.get(audio_url, follow_redirects=True).content).decode()

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Transcribe this audio."},
            {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
        ],
    }
]
client = InferenceClient("http://localhost:8000")

result = client.chat_completion(messages, model="google/gemma-4-E2B-it", max_tokens=256)
print(result.choices[0].message.content)
```

[InferenceClient](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/inference_client#huggingface_hub.InferenceClient) trả về một chuỗi đã được in ra.

```
This week, I traveled to Chicago to deliver my final farewell address to the nation, following in the tradition of presidents before me. It was an opportunity to say thank you. Whether we've seen eye to eye or rarely agreed at all, my conversations with you, the American people, in living rooms and schools, at farms and on factory floors, at diners, and on distant military outposts, all these conversations are what have kept me honest.
```

```python
import base64
from huggingface_hub.utils import httpx
from huggingface_hub import InferenceClient

audio_url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3"
audio_b64 = base64.b64encode(httpx.get(audio_url, follow_redirects=True).content).decode()

messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "Transcribe this audio."},
            {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
        ],
    }
]
client = InferenceClient("http://localhost:8000")

stream = client.chat_completion(messages, model="google/gemma-4-E2B-it", max_tokens=256, stream=True)
for chunk in stream:
    token = chunk.choices[0].delta.content
    if token:
        print(token, end="")
```

[InferenceClient](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/inference_client#huggingface_hub.InferenceClient) trả về một chuỗi đã được in ra.

```
This week, I traveled to Chicago to deliver my final farewell address to the nation, following in the tradition of presidents before me. It was an opportunity to say thank you. Whether we've seen eye to eye or rarely agreed at all, my conversations with you, the American people, in living rooms and schools, at farms and on factory floors, at diners, and on distant military outposts, all these conversations are what have kept me honest.
```

```python
import base64
from huggingface_hub.utils import httpx
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

audio_url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3"
audio_b64 = base64.b64encode(httpx.get(audio_url, follow_redirects=True).content).decode()

completion = client.chat.completions.create(
    model="google/gemma-4-E2B-it",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Transcribe this audio."},
                {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
            ],
        }
    ],
)
print(completion.choices[0].message.content)
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```
This week, I traveled to Chicago to deliver my final farewell address to the nation, following in the tradition of presidents before me. It was an opportunity to say thank you. Whether we've seen eye to eye or rarely agreed at all, my conversations with you, the American people, in living rooms and schools, at farms and on factory floors, at diners, and on distant military outposts, all these conversations are what have kept me honest.
```

```python
import base64
from huggingface_hub.utils import httpx
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

audio_url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3"
audio_b64 = base64.b64encode(httpx.get(audio_url, follow_redirects=True).content).decode()

completion = client.chat.completions.create(
    model="google/gemma-4-E2B-it",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Transcribe this audio."},
                {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
            ],
        }
    ],
    stream=True,
)

for chunk in completion:
    token = chunk.choices[0].delta.content
    if token:
        print(token, end="")
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```
This week, I traveled to Chicago to deliver my final farewell address to the nation, following in the tradition of presidents before me. It was an opportunity to say thank you. Whether we've seen eye to eye or rarely agreed at all, my conversations with you, the American people, in living rooms and schools, at farms and on factory floors, at diners, and on distant military outposts, all these conversations are what have kept me honest.
```

```shell
# First, base64-encode the audio file and build the JSON payload
AUDIO_B64=$(curl -sL https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3 | base64 -w 0)

cat <<EOF > /tmp/audio_request.json
{
  "model": "google/gemma-4-E2B-it",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Transcribe this audio."},
        {"type": "input_audio", "input_audio": {"data": "$AUDIO_B64", "format": "mp3"}}
      ]
    }
  ]
}
EOF

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @/tmp/audio_request.json
```

Lệnh trả về một chuỗi JSON.

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "message": {
        "content": "This week, I traveled to Chicago to deliver my final farewell address to the nation [...]",
        "role": "assistant"
      }
    }
  ],
  "created": 1753366665,
  "model": "google/gemma-4-E2B-it@main",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 85,
    "prompt_tokens": 200,
    "total_tokens": 285
  }
}
```

```shell
# First, base64-encode the audio file and build the JSON payload
AUDIO_B64=$(curl -sL https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3 | base64 -w 0)

cat <<EOF > /tmp/audio_request.json
{
  "model": "google/gemma-4-E2B-it",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Transcribe this audio."},
        {"type": "input_audio", "input_audio": {"data": "$AUDIO_B64", "format": "mp3"}}
      ]
    }
  ]
}
EOF

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d @/tmp/audio_request.json
```

Lệnh trả về một luồng các khối dữ liệu.

```shell
data: {"id":"cb997e1d-98b9-414a-be89-1880288610ef","choices":[{"delta":{"role":"assistant"},"index":0}],"created":1776254856,"model":"google/gemma-4-E2B-it@main","object":"chat.completion.chunk","system_fingerprint":""}

data: {"id":"cb997e1d-98b9-414a-be89-1880288610ef","choices":[{"delta":{"content":"This"},"index":0}],"created":1776254856,"model":"google/gemma-4-E2B-it@main","object":"chat.completion.chunk","system_fingerprint":""}

(...)
```

> [!WARNING]
> Loại nội dung `audio_url` là một phần mở rộng không thuộc chuẩn OpenAI và có thể thay đổi trong các phiên bản tương lai.

Bạn cũng có thể truyền audio bằng URL với kiểu nội dung `audio_url` để bỏ qua mã hóa base64.

```python
completion = client.chat.completions.create(
    model="google/gemma-4-E2B-it",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Transcribe this audio."},
                {"type": "audio_url", "audio_url": {"url": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3"}},
            ],
        }
    ],
)
```

### Hoàn thành dựa trên video

> [!WARNING]
> Loại nội dung `video_url` là một phần mở rộng không thuộc chuẩn OpenAI và có thể thay đổi trong các phiên bản tương lai.

Sử dụng kiểu nội dung `video_url` cho đầu vào video. Nếu mô hình hỗ trợ âm thanh (ví dụ: Gemma 4, Qwen2.5-Omni), máy chủ sẽ trích xuất bản âm thanh từ video và xử lý nó cùng với các khung hình trực quan.

> [!TIP]
> Xử lý video yêu cầu [torchcodec](https://github.com/pytorch/torchcodec). Cài đặt bằng `pip install torchcodec`.

```python
from huggingface_hub import InferenceClient

messages = [
    {
        "role": "user",
        "content": [
            {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}},
            {"type": "text", "text": "What is happening in the video and what is the song about?"},
        ],
    }
]
client = InferenceClient("http://localhost:8000")

result = client.chat_completion(messages, model="google/gemma-4-E2B-it", max_tokens=256)
print(result.choices[0].message.content)
```

[InferenceClient](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/inference_client#huggingface_hub.InferenceClient) trả về một chuỗi đã được in ra.

```
The video captures a live music performance at a music festival or a large concert. There are several musicians on stage, including a central figure playing an acoustic guitar and singing. The foreground is filled with the backs of the audience, indicating a large crowd watching the show. The stage is dramatically lit with bright spotlights and blue and white stage lighting, with haze and smoke creating an immersive atmosphere.

The lyrics of the song are: "I don't care 'bout street, from that fresh street, 'cause there's no problem, another one I want to be, in the storm..."
```

```python
from huggingface_hub import InferenceClient

messages = [
    {
        "role": "user",
        "content": [
            {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}},
            {"type": "text", "text": "What is happening in the video and what is the song about?"},
        ],
    }
]
client = InferenceClient("http://localhost:8000")

stream = client.chat_completion(messages, model="google/gemma-4-E2B-it", max_tokens=256, stream=True)
for chunk in stream:
    token = chunk.choices[0].delta.content
    if token:
        print(token, end="")
```

[InferenceClient](https://huggingface.co/docs/huggingface_hub/v2.4.0/en/package_reference/inference_client#huggingface_hub.InferenceClient) trả về một chuỗi đã được in ra.

```
The video captures a live music performance at a music festival or a large concert. There are several musicians on stage, including a central figure playing an acoustic guitar and singing. The foreground is filled with the backs of the audience, indicating a large crowd watching the show. The stage is dramatically lit with bright spotlights and blue and white stage lighting, with haze and smoke creating an immersive atmosphere.

The lyrics of the song are: "I don't care 'bout street, from that fresh street, 'cause there's no problem, another one I want to be, in the storm..."
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

completion = client.chat.completions.create(
    model="google/gemma-4-E2B-it",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}},
                {"type": "text", "text": "What is happening in the video and what is the song about?"},
            ],
        }
    ],
    max_tokens=256,
)
print(completion.choices[0].message.content)
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```
The video captures a live music performance at a music festival or a large concert. There are several musicians on stage, including a central figure playing an acoustic guitar and singing. The foreground is filled with the backs of the audience, indicating a large crowd watching the show. The stage is dramatically lit with bright spotlights and blue and white stage lighting, with haze and smoke creating an immersive atmosphere.

The lyrics of the song are: "I don't care 'bout street, from that fresh street, 'cause there's no problem, another one I want to be, in the storm..."
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

completion = client.chat.completions.create(
    model="google/gemma-4-E2B-it",
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}},
                {"type": "text", "text": "What is happening in the video and what is the song about?"},
            ],
        }
    ],
    max_tokens=256,
    stream=True,
)

for chunk in completion:
    token = chunk.choices[0].delta.content
    if token:
        print(token, end="")
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```
The video captures a live music performance at a music festival or a large concert. There are several musicians on stage, including a central figure playing an acoustic guitar and singing. The foreground is filled with the backs of the audience, indicating a large crowd watching the show. The stage is dramatically lit with bright spotlights and blue and white stage lighting, with haze and smoke creating an immersive atmosphere.

The lyrics of the song are: "I don't care 'bout street, from that fresh street, 'cause there's no problem, another one I want to be, in the storm..."
```

```shell
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-E2B-it",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}},
          {"type": "text", "text": "What is happening in the video and what is the song about?"}
        ]
      }
    ],
    "max_tokens": 256
  }'
```

Lệnh trả về một chuỗi JSON.

```json
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "choices": [
    {
      "finish_reason": "length",
      "index": 0,
      "message": {
        "content": "The video captures a live music performance at a music festival or a large concert [...]",
        "role": "assistant"
      }
    }
  ],
  "created": 1753366665,
  "model": "google/gemma-4-E2B-it@main",
  "object": "chat.completion",
  "usage": {
    "completion_tokens": 256,
    "prompt_tokens": 350,
    "total_tokens": 606
  }
}
```

```shell
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-E2B-it",
    "stream": true,
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}},
          {"type": "text", "text": "What is happening in the video and what is the song about?"}
        ]
      }
    ],
    "max_tokens": 256
  }'
```

Lệnh trả về một luồng các khối dữ liệu.

```shell
data: {"id":"cb997e1d-98b9-414a-be89-1880288610ef","choices":[{"delta":{"role":"assistant"},"index":0}],"created":1776254856,"model":"google/gemma-4-E2B-it@main","object":"chat.completion.chunk","system_fingerprint":""}

data: {"id":"cb997e1d-98b9-414a-be89-1880288610ef","choices":[{"delta":{"content":"Based"},"index":0}],"created":1776254856,"model":"google/gemma-4-E2B-it@main","object":"chat.completion.chunk","system_fingerprint":""}

(...)
```

### Cuộc trò chuyện nhiều lượt[[completions]]

Để có một cuộc trò chuyện nhiều lượt, hãy bao gồm lịch sử trò chuyện đầy đủ trong danh sách `messages` với các vai trò `user` và `assistant` xen kẽ. Giống như tất cả các máy chủ tương thích OpenAI, API không có trạng thái, vì vậy mỗi yêu cầu phải chứa lịch sử trò chuyện hoàn chỉnh.

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

completion = client.chat.completions.create(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    messages=[
        {"role": "user", "content": "What is the capital of France?"},
        {"role": "assistant", "content": "The capital of France is Paris."},
        {"role": "user", "content": "How many people live there?"},
    ],
)
print(completion.choices[0].message.content)
```

Câu hỏi tiếp theo “Có bao nhiêu người sống ở đó?” dựa vào ngữ cảnh trước đó, vì vậy mô hình trả lời về Paris.

```
As of 2021, the population of Paris is approximately 2.2 million people.
```

## v1/completions

API `v1/completions` dựa trên [API Completions cũ](https://platform.openai.com/docs/api-reference/completions). Khác với `/v1/chat/completions`, API này nhận một `prompt` dạng văn bản tự do thay vì các tin nhắn chat và trả về văn bản được tạo trong `choices[].text`. Điều này hữu ích cho các mô hình cơ bản (không phải instruct) và các tác vụ hoàn thành văn bản mà không cần mẫu chat. Nó cũng hỗ trợ `suffix` để chèn văn bản ở giữa.

```shell
curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B",
    "prompt": "The capital of France is",
    "max_tokens": 20
  }'
```

Lệnh trả về phản hồi sau.

```json
{
  "id": "chatcmpl-abc123",
  "object": "text_completion",
  "created": 1234567890,
  "model": "Qwen/Qwen2.5-0.5B@main",
  "choices": [
    {
      "text": " Paris, and the capital of the United States is Washington, D.C.",
      "index": 0,
      "logprobs": null,
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 5,
    "completion_tokens": 16,
    "total_tokens": 21
  }
}
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

# Non-streaming
completion = client.completions.create(
    model="Qwen/Qwen2.5-0.5B",
    prompt="The capital of France is",
    max_tokens=20,
)
print(completion.choices[0].text)
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về các nội dung sau.

```shell
 Paris, and the capital of the United States is Washington, D.C.
```

Streaming cũng được hỗ trợ.

```python
stream = client.completions.create(
    model="Qwen/Qwen2.5-0.5B",
    prompt="The capital of France is",
    max_tokens=20,
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].text, end="")
```

## v1/responses

[Responses API](https://platform.openai.com/docs/api-reference/responses) là điểm cuối API mới nhất của OpenAI cho việc tạo nội dung. Nó hỗ trợ các tương tác có trạng thái và tích hợp các công cụ tích hợp sẵn để mở rộng khả năng của mô hình. OpenAI [khuyến nghị](https://platform.openai.com/docs/guides/migrate-to-responses) sử dụng Responses API thay vì Chat Completions API cho các dự án mới.

API `v1/responses` hỗ trợ các yêu cầu văn bản, hình ảnh, âm thanh và video thông qua lệnh `curl` và client [OpenAI](https://platform.openai.com/docs/quickstart).

### Phản hồi dựa trên văn bản

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

response = client.responses.create(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    input="Tell me a three sentence bedtime story about a unicorn.",
    max_output_tokens=256,
    stream=False,
)
print(response.output[0].content[0].text)
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```shell
Once upon a time, in a faraway land, there lived a beautiful unicorn named Luna [...]
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

response = client.responses.create(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    input="Tell me a three sentence bedtime story about a unicorn.",
    max_output_tokens=256,
    stream=True,
)

for event in response:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="")
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```shell
Once upon a time, in a faraway land, there lived a beautiful unicorn named Luna [...]
```

```shell
curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "input": "Tell me a three sentence bedtime story about a unicorn.",
    "max_output_tokens": 256,
    "stream": false
  }'
```

Lệnh trả về một chuỗi JSON.

```json
{
  "id": "resp_8693af9b-b561-4267-bd1a-22d1b43284cb",
  "created_at": 1776258580.7114341,
  "model": "Qwen/Qwen2.5-0.5B-Instruct@main",
  "object": "response",
  "output": [
    {
      "id": "msg_8693af9b-b561-4267-bd1a-22d1b43284cb",
      "content": [
        {
          "annotations": [],
          "text": "Once upon a time, in a faraway land, there lived a beautiful unicorn named Luna [...]",
          "type": "output_text"
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "status": "completed"
}
```

```shell
curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-0.5B-Instruct",
    "stream": true,
    "input": "Tell me a three sentence bedtime story about a unicorn.",
    "max_output_tokens": 256
  }'
```

Lệnh trả về một luồng các khối dữ liệu.

```shell
data: {"response":{"id":"resp_req_0","created_at":1754059817.783648,"model":"Qwen/Qwen2.5-0.5B-Instruct@main","object":"response","output":[],"status":"queued"},"sequence_number":0,"type":"response.created"}

data: {"content_index":0,"delta":"Once ","item_id":"msg_req_0","output_index":0,"sequence_number":5,"type":"response.output_text.delta"}

data: {"content_index":0,"delta":"upon ","item_id":"msg_req_0","output_index":0,"sequence_number":6,"type":"response.output_text.delta"}

(...)
```

### Phản hồi dựa trên hình ảnh

API Responses cũng hỗ trợ đầu vào hình ảnh, âm thanh và video.

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

response = client.responses.create(
    model="Qwen/Qwen2.5-VL-7B-Instruct",
    input=[
        {"type": "input_text", "text": "What's in this image?"},
        {
            "type": "input_image",
            "image_url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg",
        },
    ],
    max_output_tokens=256,
    stream=False,
)
print(response.output[0].content[0].text)
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```xmp
The image depicts an astronaut in a space suit standing on what appears to be the surface of the moon, given the barren, rocky landscape and the dark sky in the background. The astronaut is holding a large egg that has cracked open, revealing a small creature inside. The scene is imaginative and playful, combining elements of space exploration with a whimsical twist involving the egg and the creature.
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

response = client.responses.create(
    model="Qwen/Qwen2.5-VL-7B-Instruct",
    input=[
        {"type": "input_text", "text": "What's in this image?"},
        {
            "type": "input_image",
            "image_url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg",
        },
    ],
    max_output_tokens=256,
    stream=True,
)

for event in response:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="")
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```xmp
The image depicts an astronaut in a space suit standing on what appears to be the surface of the moon, given the barren, rocky landscape and the dark sky in the background. The astronaut is holding a large egg that has cracked open, revealing a small creature inside. The scene is imaginative and playful, combining elements of space exploration with a whimsical twist involving the egg and the creature.
```

```shell
curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-VL-7B-Instruct",
    "input": [
      {"type": "input_text", "text": "What'\''s in this image?"},
      {"type": "input_image", "image_url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"}
    ],
    "max_output_tokens": 256,
    "stream": false
  }'
```

Lệnh trả về một chuỗi JSON.

```json
{
  "id": "resp_f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "created_at": 1776258580.7114341,
  "model": "Qwen/Qwen2.5-VL-7B-Instruct@main",
  "object": "response",
  "output": [
    {
      "id": "msg_f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "content": [
        {
          "annotations": [],
          "text": "The image depicts an astronaut in a space suit standing on what appears to be the surface of the moon [...]",
          "type": "output_text"
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "status": "completed"
}
```

```shell
curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-VL-7B-Instruct",
    "stream": true,
    "input": [
      {"type": "input_text", "text": "What'\''s in this image?"},
      {"type": "input_image", "image_url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/diffusers/astronaut.jpg"}
    ],
    "max_output_tokens": 256
  }'
```

Lệnh trả về một luồng các khối dữ liệu.

```shell
data: {"response":{"id":"resp_f47ac10b-58cc-4372-a567-0e02b2c3d479","created_at":1776258580.7114341,"model":"Qwen/Qwen2.5-VL-7B-Instruct@main","object":"response","output":[],"status":"queued"},"sequence_number":0,"type":"response.created"}

data: {"content_index":0,"delta":"The ","item_id":"msg_f47ac10b","output_index":0,"sequence_number":5,"type":"response.output_text.delta"}

(...)
```

### Phản hồi dựa trên âm thanh

```python
import base64
from huggingface_hub.utils import httpx
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

audio_url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3"
audio_b64 = base64.b64encode(httpx.get(audio_url, follow_redirects=True).content).decode()

response = client.responses.create(
    model="google/gemma-4-E2B-it",
    input=[
        {"type": "input_text", "text": "Transcribe this audio."},
        {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
    ],
    max_output_tokens=256,
    stream=False,
)
print(response.output[0].content[0].text)
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```
This week, I traveled to Chicago to deliver my final farewell address to the nation, following in the tradition of presidents before me. It was an opportunity to say thank you. Whether we've seen eye to eye or rarely agreed at all, my conversations with you, the American people, in living rooms and schools, at farms and on factory floors, at diners, and on distant military outposts, all these conversations are what have kept me honest.
```

```python
import base64
from huggingface_hub.utils import httpx
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

audio_url = "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3"
audio_b64 = base64.b64encode(httpx.get(audio_url, follow_redirects=True).content).decode()

response = client.responses.create(
    model="google/gemma-4-E2B-it",
    input=[
        {"type": "input_text", "text": "Transcribe this audio."},
        {"type": "input_audio", "input_audio": {"data": audio_b64, "format": "mp3"}},
            ],
        }
    ],
    max_output_tokens=256,
    stream=True,
)

for event in response:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="")
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```
This week, I traveled to Chicago to deliver my final farewell address to the nation, following in the tradition of presidents before me. It was an opportunity to say thank you. Whether we've seen eye to eye or rarely agreed at all, my conversations with you, the American people, in living rooms and schools, at farms and on factory floors, at diners, and on distant military outposts, all these conversations are what have kept me honest.
```

```shell
# First, base64-encode the audio file and build the JSON payload
AUDIO_B64=$(curl -sL https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3 | base64 -w 0)

cat <<EOF > /tmp/audio_request.json
{
  "model": "google/gemma-4-E2B-it",
  "input": [
    {"type": "input_text", "text": "Transcribe this audio."},
    {"type": "input_audio", "input_audio": {"data": "$AUDIO_B64", "format": "mp3"}}
  ],
  "max_output_tokens": 256,
  "stream": false
}
EOF

curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d @/tmp/audio_request.json
```

Lệnh trả về một chuỗi JSON.

```json
{
  "id": "resp_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": 1776258580.7114341,
  "model": "google/gemma-4-E2B-it@main",
  "object": "response",
  "output": [
    {
      "id": "msg_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "content": [
        {
          "annotations": [],
          "text": "This week, I traveled to Chicago to deliver my final farewell address to the nation [...]",
          "type": "output_text"
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "status": "completed"
}
```

```shell
# First, base64-encode the audio file and build the JSON payload
AUDIO_B64=$(curl -sL https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3 | base64 -w 0)

cat <<EOF > /tmp/audio_request.json
{
  "model": "google/gemma-4-E2B-it",
  "stream": true,
  "input": [
    {"type": "input_text", "text": "Transcribe this audio."},
    {"type": "input_audio", "input_audio": {"data": "$AUDIO_B64", "format": "mp3"}}
  ],
  "max_output_tokens": 256
}
EOF

curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d @/tmp/audio_request.json
```

Lệnh trả về một luồng các khối dữ liệu.

```shell
data: {"response":{"id":"resp_a1b2c3d4-e5f6-7890-abcd-ef1234567890","created_at":1776258580.7114341,"model":"google/gemma-4-E2B-it@main","object":"response","output":[],"status":"queued"},"sequence_number":0,"type":"response.created"}

data: {"content_index":0,"delta":"This ","item_id":"msg_a1b2c3d4","output_index":0,"sequence_number":5,"type":"response.output_text.delta"}

(...)
```

> [!WARNING]
> Loại nội dung `audio_url` là một phần mở rộng không thuộc chuẩn OpenAI và có thể thay đổi trong các phiên bản tương lai.

Bạn cũng có thể truyền audio bằng URL với kiểu nội dung `audio_url` để bỏ qua mã hóa base64.

```python
response = client.responses.create(
    model="google/gemma-4-E2B-it",
    input=[
        {"type": "input_text", "text": "Transcribe this audio."},
        {"type": "audio_url", "audio_url": {"url": "https://huggingface.co/datasets/hf-internal-testing/dummy-audio-samples/resolve/main/obama_first_45_secs.mp3"}},
    ],
    max_output_tokens=256,
    stream=False,
)
```

### Phản hồi dựa trên video

> [!WARNING]
> Loại nội dung `video_url` là một phần mở rộng không thuộc chuẩn OpenAI và có thể thay đổi trong các phiên bản tương lai.

> [!TIP]
> Xử lý video yêu cầu [torchcodec](https://github.com/pytorch/torchcodec). Cài đặt bằng `pip install torchcodec`.

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

response = client.responses.create(
    model="google/gemma-4-E2B-it",
    input=[
        {"type": "input_text", "text": "What is happening in the video and what is the song about?"},
        {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}},
    ],
    max_output_tokens=256,
    stream=False,
)
print(response.output[0].content[0].text)
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```
The video captures a live music performance at a music festival or a large concert. There are several musicians on stage, including a central figure playing an acoustic guitar and singing. The foreground is filled with the backs of the audience, indicating a large crowd watching the show. The stage is dramatically lit with bright spotlights and blue and white stage lighting, with haze and smoke creating an immersive atmosphere.

The lyrics of the song are: "I don't care 'bout street, from that fresh street, 'cause there's no problem, another one I want to be, in the storm..."
```

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

response = client.responses.create(
    model="google/gemma-4-E2B-it",
    input=[
        {"type": "input_text", "text": "What is happening in the video and what is the song about?"},
        {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}},
    ],
    max_output_tokens=256,
    stream=True,
)

for event in response:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="")
```

Client [OpenAI](https://platform.openai.com/docs/quickstart) trả về một chuỗi đã được in ra.

```
The video captures a live music performance at a music festival or a large concert. There are several musicians on stage, including a central figure playing an acoustic guitar and singing. The foreground is filled with the backs of the audience, indicating a large crowd watching the show. The stage is dramatically lit with bright spotlights and blue and white stage lighting, with haze and smoke creating an immersive atmosphere.

The lyrics of the song are: "I don't care 'bout street, from that fresh street, 'cause there's no problem, another one I want to be, in the storm..."
```

```shell
curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-E2B-it",
    "input": [
      {"type": "input_text", "text": "What is happening in the video and what is the song about?"},
      {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}}
    ],
    "max_output_tokens": 256,
    "stream": false
  }'
```

Lệnh trả về một chuỗi JSON.

```json
{
  "id": "resp_b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "created_at": 1776258580.7114341,
  "model": "google/gemma-4-E2B-it@main",
  "object": "response",
  "output": [
    {
      "id": "msg_b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "content": [
        {
          "annotations": [],
          "text": "The video captures a live music performance at a music festival or a large concert [...]",
          "type": "output_text"
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "status": "completed"
}
```

```shell
curl http://localhost:8000/v1/responses \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google/gemma-4-E2B-it",
    "stream": true,
    "input": [
      {"type": "input_text", "text": "What is happening in the video and what is the song about?"},
      {"type": "video_url", "video_url": {"url": "https://huggingface.co/datasets/merve/vlm_test_images/resolve/main/concert.mp4"}}
    ],
    "max_output_tokens": 256
  }'
```

Lệnh trả về một luồng các khối dữ liệu.

```shell
data: {"response":{"id":"resp_b2c3d4e5-f6a7-8901-bcde-f12345678901","created_at":1776258580.7114341,"model":"google/gemma-4-E2B-it@main","object":"response","output":[],"status":"queued"},"sequence_number":0,"type":"response.created"}

data: {"content_index":0,"delta":"Based ","item_id":"msg_b2c3d4e5","output_index":0,"sequence_number":5,"type":"response.output_text.delta"}

(...)
```

### Cuộc trò chuyện nhiều lượt[[responses]]

Đối với các cuộc trò chuyện nhiều lượt, hãy truyền một danh sách các tin nhắn có các khóa `role` trong trường `input`. Giống như tất cả các máy chủ tương thích với OpenAI, API không có trạng thái, do đó mỗi yêu cầu phải chứa lịch sử trò chuyện đầy đủ.

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<random_string>")

response = client.responses.create(
    model="Qwen/Qwen2.5-0.5B-Instruct",
    input=[
        {"role": "user", "content": "What is the capital of France?"},
        {"role": "assistant", "content": "The capital of France is Paris."},
        {"role": "user", "content": "How many people live there?"},
    ],
    max_output_tokens=256,
    stream=False,
)
print(response.output[0].content[0].text)
```

Câu hỏi tiếp theo “Có bao nhiêu người sống ở đó?” dựa vào ngữ cảnh trước đó, vì vậy mô hình trả lời về Paris.

```
As of 2021, Paris has a population of approximately 2.8 million people.
```

## v1/systemone

Điểm cuối `v1/systemone` trả lời các câu hỏi có kiểu dữ liệu về một `state` chung, tuân theo [API System One của TypeSafe](https://api.typesafe.ai/openapi.json). Hãy sử dụng nó cho các quyết định như định tuyến một vé hỗ trợ, đánh giá mức độ khẩn cấp, hoặc chọn một hành động.

Các yêu cầu được xử lý bởi [DecisionPipeline](/docs/transformers/v5.23.0/vi/main_classes/pipelines#transformers.DecisionPipeline) bao quanh model được phục vụ, do đó endpoint và pipeline xây dựng cùng các prompt và trả về cùng các câu trả lời. Model chấm điểm các câu trả lời được phép mà không tạo ra văn bản, trong một lần forward pass cho mỗi prompt. Endpoint này hỗ trợ các model tự hồi quy có chat template;

Gửi một mô hình, trạng thái cần đánh giá và các câu hỏi được đặt tên theo tên:

```shell
curl http://localhost:8000/v1/systemone \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-1.5B-Instruct",
    "state": "Our integration has been failing for 3 days and we are losing sales!",
    "questions": {
      "team": {
        "type": "choice",
        "instructions": "Which team handles this?",
        "criteria": {"billing": null, "technical": "Bugs or integration problems"}
      },
      "urgency": {
        "type": "score",
        "instructions": "How urgent is this ticket?",
        "criteria": ["low", "medium", "high"]
      },
      "upset": {"type": "noul", "instructions": "Is the customer upset?"}
    }
  }'
```

Cài đặt [TypeSafe SDK](https://github.com/typesafe-ai/typesafe-sdk-js) cho Node.js 20 trở lên:

```shell
npm install @typesafe-ai/sdk
```

Đặt `baseURL` là gốc của máy chủ; SDK sẽ thêm `/v1/systemone`. SDK yêu cầu một khóa API, nhưng một giá trị thay thế vẫn hoạt động với máy chủ cục bộ.

```typescript
import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  baseURL: "http://localhost:8000",
  apiKey: "<random_string>",
});

const response = await client.systemOne({
  model: "Qwen/Qwen2.5-1.5B-Instruct",
  state: "Our integration has been failing for 3 days and we are losing sales!",
  questions: {
    team: choice("Which team handles this?", {
      billing: null,
      technical: "Bugs or integration problems",
    }),
    urgency: score("How urgent is this ticket?", ["low", "medium", "high"]),
    upset: noul("Is the customer upset?"),
  },
});

console.log(response.answers.team.choice);
console.log(response.answers.urgency.score);
console.log(response.answers.upset.noul);
```

Client in ra đội được chọn, điểm khẩn cấp và xác suất khách hàng đang bực bội. Ví dụ:

```shell
technical
1.6739138662815094
0.851952850818634
```

Câu trả lời sử dụng cùng tên câu hỏi. Ví dụ:

```json
{
  "model": "Qwen/Qwen2.5-1.5B-Instruct",
  "answers": {
    "team": {"type": "choice", "choice": "technical", "probabilities": {"billing": 0.000006962256520637311, "technical": 0.999993085861206}, "confidence": 0.9999861717224121},
    "urgency": {"type": "score", "score": 1.6739138662815094, "legend": {"0": "low", "1": "medium", "2": "high"}, "probabilities": {"0": 0.0031353600788861513, "1": 0.31981542706489563, "2": 0.6770492196083069}, "confidence": 0.5108707791659981},
    "upset": {"type": "noul", "noul": 0.851952850818634}
  },
  "usage": {"input_tokens": 213, "output_tokens": 0}
}
```

| Loại câu hỏi | `criteria` | Câu trả lời |
| :--- | :--- | :--- |
| `choice` | Tên các tùy chọn được ánh xạ đến mô tả, có thể là `null`. | Phương án có khả năng cao nhất, xác suất của các phương án và độ tin cậy. |
| `score` | Mô tả các cấp độ được sắp xếp từ thấp đến cao. | Chỉ số mức có trọng số xác suất, các xác suất, chú giải và độ tin cậy. |
| `noul` | Mô tả tùy chọn cho `true` và `false`. | Xác suất của `true`. |

`state`, tùy chọn `instructions`, và mô tả có thể chứa văn bản hoặc các đối tượng và mảng JSON. Mỗi yêu cầu chấp nhận tối đa 64 câu hỏi, với ít nhất một lựa chọn hoặc mức điểm cho mỗi câu hỏi và tối đa một cho mỗi nhãn câu trả lời (26 với các nhãn mặc định `A`–`Z`).

Các câu hỏi được xác thực giống như của [DecisionPipeline](/docs/transformers/v5.23.0/vi/main_classes/pipelines#transformers.DecisionPipeline), trước khi mô hình được nạp. Một yêu cầu không hợp lệ sẽ trả về `422`, trong đó thông báo liệt kê mọi câu hỏi không hợp lệ, mỗi câu kèm theo một ví dụ hợp lệ, và gợi ý các kiểu hoặc trường tương tự cho các trường hợp đánh sai chính tả:

```text
Question 'team': expected a `type` among noul, choice, score, got type 'Choice'. Did you mean 'choice'?
Question 'upset': unknown field 'instruction'. Did you mean 'instructions'? A noul question looks like {"type": "noul", ...}
```

Đối với các model có khả năng thị giác, hãy thêm `assets`, giống như trong System One API: tối đa bốn hình ảnh được gán khóa bằng một placeholder do bạn chọn (UUID là an toàn nhất). Bất cứ đâu một placeholder xuất hiện trong chuỗi của `state`, `instructions` hoặc `criteria`, model sẽ nhìn thấy hình ảnh tại đó. Một asset là `{"type": "image", "format": "png", "data_base64": "..."}`; các URL hình ảnh từ xa không được chấp nhận. Model cần một processor xử lý hình ảnh.

```json
{
  "model": "Qwen/Qwen2.5-VL-3B-Instruct",
  "state": "The customer sent 6f1c0e2a and asks if it is damaged.",
  "assets": {"6f1c0e2a": {"type": "image", "format": "png", "data_base64": "iVBORw0..."}},
  "questions": {"damaged": {"type": "noul", "instructions": "Is the product in the photo damaged?"}}
}
```

### Cấu hình quyết định

Các mô hình quyết định hiện chưa có một tiêu chuẩn chung để lưu trữ prompt, nhãn câu trả lời và cài đặt hiệu chuẩn. Những yếu tố này khác nhau giữa các triển khai mô hình, do đó `--decision-config` cho phép bạn cung cấp chúng một cách tường minh.

Mặc định, các câu hỏi sử dụng prompt dự phòng và chat template của mô hình với tính năng suy nghĩ bị tắt. Nhãn câu trả lời là `A`–`Z` cho các lựa chọn và điểm số, và `Yes`/`No` cho giá trị boolean. Xác suất là softmax trên các nhãn này ở nhiệt độ 1.

Truyền `--decision-config` để ghi đè các giá trị mặc định này cho một mô hình:

```shell
transformers serve openjev/openjev --decision-config decision.json
```

Tệp JSON hỗ trợ ba trường tùy chọn:

| Trường | Ý nghĩa |
| :--- | :--- |
| `labels` | Nhãn câu trả lời theo loại câu hỏi, theo thứ tự các lựa chọn (`true`, sau đó là `false` đối với `noul`). Mỗi nhãn phải là một token đơn lẻ riêng biệt và đã biết. |
| `temperature` | Nhiệt độ dương theo loại câu hỏi, được áp dụng dưới dạng `softmax(label_logits / temperature)`. |
| `chat_template` | Một mẫu Jinja inline thay thế cho toàn bộ prompt, bao gồm định dạng chat và tiền tố của trợ lý. |

Ví dụ, để thay đổi nhãn và hiệu chuẩn trong khi giữ nguyên prompt mặc định:

```json
{
  "labels": {"noul": ["A", "B"]},
  "temperature": {"choice": 0.85, "score": 0.85, "noul": 1.5547129}
}
```

Một template tùy chỉnh, ở đây dành cho Gemma 3, sẽ viết toàn bộ prompt và `<|mark|>` tại vị trí đọc câu trả lời. Các chuỗi chứa hình ảnh được truyền đến dưới dạng danh sách các phần văn bản và hình ảnh:

```jinja
{%- macro text(x) -%}
{%- if x is string or x is none %}{{ x or "" }}{% elif x is mapping %}{{ x|tojson }}{% else -%}
{%- for part in x %}{% if part.type == "image" %}<start_of_image>{% else %}{{ part.text }}{% endif %}{% endfor -%}
{%- endif -%}
{%- endmacro -%}
<start_of_turn>user
{{ text(state) }}

{{ text(question.instructions) }}
{% for option in question.options %}{{ question.labels[loop.index0] }}. {{ option }}: {{ text(question.descriptions[loop.index0]) }}
{% endfor %}<end_of_turn>
<start_of_turn>model
<|mark|>
```

Viết trực tiếp vào `chat_template` trong tệp `--decision-config`, hoặc cung cấp dưới dạng `decision_template.jinja` đặt cạnh `decision.json` trong kho mô hình.

## v1/audio/transcriptions

Endpoint `v1/audio/transcriptions` chuyển văn bản từ giọng nói bằng cách sử dụng các mô hình speech-to-text. Nó tuân theo định dạng [Audio transcription API](https://platform.openai.com/docs/api-reference/audio/createTranscription).

```shell
curl -X POST http://localhost:8000/v1/audio/transcriptions \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/audio.wav" \
  -F "model=openai/whisper-large-v3"
```

Lệnh trả về phản hồi sau.

```shell
{
  "text": "Transcribed text from the audio file",
}
```

## v1/models

Điểm cuối `v1/models` quét bộ nhớ đệm Hugging Face cục bộ của bạn và trả về danh sách các model đã tải xuống ở định dạng tương thích OpenAI. Các công cụ bên thứ ba sử dụng điểm cuối này để phát hiện các model khả dụng.

Tải xuống một mô hình trước khi chạy `transformers serve`.

```bash
transformers download Qwen/Qwen2.5-0.5B-Instruct
```

Sau khi tải xuống, mô hình sẽ xuất hiện trong các phản hồi `/v1/models`.

```shell
curl http://localhost:8000/v1/models
```

Endpoint trả về một đối tượng JSON chứa các model khả dụng.

## Tải mô hình

Endpoint `/load_model` tải trước một model và truyền tiến trình qua [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events) (SSE). CLI `transformers chat` sử dụng nó tự động để người dùng thấy tiến trình tải xuống và nạp model thay vì một prompt treo. Hãy dùng nó để làm nóng model trước khi gửi các yêu cầu suy luận.

### Yêu cầu

```shell
curl -N -X POST http://localhost:8000/load_model \
  -H "Content-Type: application/json" \
  -d '{"model": "Qwen/Qwen2.5-0.5B-Instruct"}'
```

Trường `model` là định danh mô hình Hugging Face, tùy chọn có hậu tố `@revision` (`Qwen/Qwen2.5-0.5B-Instruct@main`). Nếu bỏ qua revision, mặc định sẽ là `main`.

### Phản hồi

Phản hồi là một luồng SSE (`Content-Type: text/event-stream`). Mỗi khung là một đối tượng JSON trên dòng `data:`.

```
data: {"status": "loading", "model": "Qwen/Qwen2.5-0.5B-Instruct@main", "stage": "processor"}
```

Mỗi sự kiện chứa ít nhất trường `status` và `model`. Các trường bổ sung phụ thuộc vào trạng thái.

| Trường | Có mặt khi | Mô tả |
|-------|-------------|-------------|
| `status` | Luôn luôn | `loading`, `ready` hoặc `error` |
| `model` | Luôn luôn | Canonical `model_id@revision` |
| `stage` | `status == "loading"` | Một trong các `processor`, `config`, `download`, `weights` (xem các giai đoạn bên dưới) |
| `progress` | các giai đoạn `download` và `weights` | Đối tượng có `current` và `total` (số nguyên hoặc null) |
| `cached` | `status == "ready"` | `true` nếu mô hình đã nằm trong bộ nhớ |
| `message` | `status == "error"` | Mô tả lỗi |

### Các giai đoạn

Quá trình tải diễn ra theo thứ tự qua các giai đoạn này. Một số giai đoạn có thể bị bỏ qua (`download` sẽ bị bỏ qua khi các tệp đã được lưu trong bộ nhớ đệm cục bộ).

| Giai đoạn | Đã có tiến triển chưa? | Mô tả |
|-------|---------------|-------------|
| `processor` | Không | Tải tokenizer/processor |
| `config` | Không | Tải cấu hình mô hình |
| `download` | Có (bít) | Tải tệp tin mô hình |
| `weights` | Có (các mục) | Tải các tensor trọng số vào bộ nhớ |

Dòng kết thúc bằng đúng một sự kiện cuối, `ready` (thành công) hoặc `error` (thất bại).

## Timeout

`transformers serve` xử lý các yêu cầu cho bất kỳ model nào. Mỗi model được nạp theo yêu cầu và giữ trong bộ nhớ GPU. Các model sẽ tự động được gỡ bỏ sau 300 giây không hoạt động để giải phóng bộ nhớ GPU. Đặt `--model-timeout` thành một giá trị khác tính bằng giây, hoặc `-1` để tắt việc gỡ bỏ.

```shell
transformers serve --model-timeout 400
```

### Đang tải các ví dụ

Các ví dụ bên dưới hiển thị phản hồi cho một mô hình vừa được tải xuống, một mô hình được nạp từ bộ nhớ đệm cục bộ của bạn (bỏ qua giai đoạn tải xuống) và một mô hình đã có trong bộ nhớ.

```
data: {"status": "loading", "model": "org/model@main", "stage": "processor"}
data: {"status": "loading", "model": "org/model@main", "stage": "config"}
data: {"status": "loading", "model": "org/model@main", "stage": "download", "progress": {"current": 0, "total": 269100000}}
data: {"status": "loading", "model": "org/model@main", "stage": "download", "progress": {"current": 134600000, "total": 269100000}}
data: {"status": "loading", "model": "org/model@main", "stage": "download", "progress": {"current": 269100000, "total": 269100000}}
data: {"status": "loading", "model": "org/model@main", "stage": "weights", "progress": {"current": 1, "total": 272}}
data: {"status": "loading", "model": "org/model@main", "stage": "weights", "progress": {"current": 272, "total": 272}}
data: {"status": "ready", "model": "org/model@main", "cached": false}
```

```
data: {"status": "loading", "model": "org/model@main", "stage": "processor"}
data: {"status": "loading", "model": "org/model@main", "stage": "config"}
data: {"status": "loading", "model": "org/model@main", "stage": "weights", "progress": {"current": 1, "total": 272}}
data: {"status": "loading", "model": "org/model@main", "stage": "weights", "progress": {"current": 272, "total": 272}}
data: {"status": "ready", "model": "org/model@main", "cached": false}
```

```
data: {"status": "ready", "model": "org/model@main", "cached": true}
```

## Gọi công cụ

Máy chủ `transformers serve` hỗ trợ gọi hàm theo phong cách OpenAI. Các mô hình được huấn luyện cho việc sử dụng công cụ sẽ tạo ra các lời gọi hàm có cấu trúc để ứng dụng của bạn thực thi.

> [!NOTE]
> Tool calling hoạt động với bất kỳ model nào có tokenizer khai báo tool call tokens. Qwen và Gemma 4 hoạt động ngay lập tức. Mở một [issue](https://github.com/huggingface/transformers/issues/new/choose) để yêu cầu hỗ trợ cho một model cụ thể.

Định nghĩa các công cụ dưới dạng danh sách các thông số hàm tuân theo định dạng OpenAI.

```py
import json
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<KEY>")

tools = [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the current weather in a location",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city name, e.g. San Francisco"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"],
            "description": "temperature unit"
          }
        },
        "required": ["location"]
      }
    }
  }
]
```

Tùy chỉnh quá trình tạo bằng cách truyền các tham số [GenerationConfig](/docs/transformers/v5.23.0/vi/main_classes/text_generation#transformers.GenerationConfig) vào đối số `extra_body` trong [create](https://platform.openai.com/docs/api-reference/responses/create).

```py
generation_config = {
  "max_new_tokens": 512,
  "temperature": 0.7,
  "top_p": 0.9,
  "top_k": 50,
  "do_sample": True,
  "repetition_penalty": 1.1,
  "no_repeat_ngram_size": 3,
}

response = client.responses.create(
  model="Qwen/Qwen2.5-7B-Instruct",
  instructions="You are a helpful weather assistant. Use the get_weather tool to answer questions.",
  input="What's the weather like in San Francisco?",
  tools=tools,
  stream=True,
  extra_body={"generation_config": json.dumps(generation_config)}
)

for event in response:
  print(event)
```

### Gọi công cụ đa lượt

Sau khi model trả về một tool call, hãy thực thi hàm cục bộ, sau đó gửi kết quả trở lại trong một yêu cầu tiếp theo để nhận câu trả lời cuối cùng từ model. Mẫu này có chút khác biệt giữa hai API. Xem [hướng dẫn function calling của OpenAI](https://developers.openai.com/api/docs/guides/function-calling?api-mode=chat) để biết thông số kỹ thuật đầy đủ.

Các ví dụ dưới đây tái sử dụng danh sách `tools` được định nghĩa ở trên.

Truyền kết quả công cụ dưới dạng thông điệp `role: "tool"` với `tool_call_id` tương ứng.

```py
# Model returns a tool call
messages = [{"role": "user", "content": "What's the weather like in San Francisco?"}]
response = client.chat.completions.create(
    model="Qwen/Qwen2.5-7B-Instruct",
    messages=messages,
    tools=tools,
)
assistant_message = response.choices[0].message

# Execute the tool locally
tool_call = assistant_message.tool_calls[0]
result = {"temperature": 22, "condition": "sunny"}  # your actual function call here

# Send the tool result back
messages.append(assistant_message)
messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps(result),
})
final_response = client.chat.completions.create(
    model="Qwen/Qwen2.5-7B-Instruct",
    messages=messages,
    tools=tools,
)
print(final_response.choices[0].message.content)
```

Truyền kết quả công cụ dưới dạng mục `function_call_output` trong danh sách `input` của yêu cầu tiếp theo.

```py
user_message = {"role": "user", "content": "What's the weather like in San Francisco?"}
response = client.responses.create(
    model="Qwen/Qwen2.5-7B-Instruct",
    input=[user_message],
    tools=tools,
    stream=False,
)
tool_call = next(item for item in response.output if item.type == "function_call")

result = {"temperature": 22, "condition": "sunny"}

final_response = client.responses.create(
    model="Qwen/Qwen2.5-7B-Instruct",
    input=[
        user_message,
        tool_call.model_dump(exclude_none=True),
        {"type": "function_call_output", "call_id": tool_call.call_id, "output": json.dumps(result)},
    ],
    tools=tools,
    stream=False,
)
print(final_response.output_text)
```

## Lý luận

Các mô hình suy luận phát ra một chuỗi suy nghĩ ẩn trước câu trả lời cuối cùng. Máy chủ phát hiện các đoạn suy nghĩ này, loại bỏ các ký hiệu phân tách khỏi câu trả lời hiển thị và hiển thị văn bản suy luận trong một trường riêng biệt để các client có thể render chúng riêng biệt.

- Chat Completions trả về suy luận dưới dạng `reasoning_content` trong thông điệp của trợ lý.
- Responses API trả về suy luận dưới dạng mục đầu ra `reasoning` đứng trước mục `message`.

Việc phát hiện suy luận dựa vào [mẫu phản hồi](../chat_response_parsing), cho biết vị trí bắt đầu và kết thúc của một đoạn suy nghĩ. Máy chủ sẽ tìm mẫu này ở hai vị trí, theo thứ tự.

1. Thuộc tính `response_template` của tokenizer, nếu model có kèm theo.
2. Một phương án dự phòng tích hợp, khớp theo kiến trúc mô hình, dành cho các tokenizer chưa được cung cấp kèm theo một template.

Các mô hình không có cả hai sẽ được phục vụ mà không có phân tích phản hồi. Văn bản thô đã giải mã được trả về dưới dạng `content` và không có trường suy luận nào được hiển thị, ngay cả khi mô hình phát ra các thẻ `<think>...</think>`.

### Bật suy luận trên máy chủ

Sử dụng `--reasoning` để kiểm soát việc chat template có phát ra các token suy nghĩ hay không.

| Giá trị | Hành vi |
|---|---|
| `auto` (mặc định) | Giao cho mặc định của mẫu trò chuyện. |
| `on` | Bật ép buộc suy nghĩ bằng cách đặt `enable_thinking=True` trong kwargs của chat template. |
| `off` | Tắt chế độ suy nghĩ bằng cách đặt `enable_thinking=False`. |

```sh
transformers serve Qwen/Qwen3-1.7B --reasoning on
```

> [!WARNING]
> Không phải tất cả các model đều hỗ trợ reasoning. `--reasoning` chỉ hoạt động khi chat template của model xử lý biến `enable_thinking` (hoặc khi tokenizer của nó khai báo các thinking delimiters). Đối với các model khác, cờ này sẽ bị bỏ qua một cách im lặng.

`--reasoning on` và `--reasoning off` hoạt động bằng cách đặt biến chat template `enable_thinking`. Một số chat template sử dụng tên biến khác để bật/tắt chế độ suy nghĩ, hoặc chấp nhận các biến bổ sung làm thay đổi cách prompt được render. Truyền bất kỳ biến chat template nào trực tiếp bằng `--chat-template-kwargs` dưới dạng một đối tượng JSON.

```sh
transformers serve Qwen/Qwen3-1.7B \
  --chat-template-kwargs '{"enable_thinking": true}'
```

Client cũng có thể gửi `chat_template_kwargs` trong body của yêu cầu để ghi đè các giá trị mặc định của server cho một yêu cầu duy nhất, mà không cần khởi động lại server.

### Chat Completions

Phản hồi không dạng luồng bao gồm `reasoning_content` cùng với `content` trong thông điệp của trợ lý.

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="<KEY>")

completion = client.chat.completions.create(
    model="Qwen/Qwen3-1.7B",
    messages=[{"role": "user", "content": "What is 17 * 23?"}],
)
message = completion.choices[0].message
print("reasoning:", message.reasoning_content)
print("answer:", message.content)
```

Streaming phát ra các delta `reasoning_content` trước các delta `content`. Nối từng trường riêng biệt.

```python
chunks = list(
    client.chat.completions.create(
        model="Qwen/Qwen3-1.7B",
        messages=[{"role": "user", "content": "What is 17 * 23?"}],
        stream=True,
    )
)
reasoning = "".join(getattr(c.choices[0].delta, "reasoning_content", None) or "" for c in chunks)
content = "".join(c.choices[0].delta.content or "" for c in chunks)
```

```shell
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-1.7B",
    "messages": [{"role": "user", "content": "What is 17 * 23?"}],
    "chat_template_kwargs": {"enable_thinking": true}
  }'
```

Phản hồi bao gồm `reasoning_content` trong thông điệp của trợ lý.

```json
{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "17 * 23 = 391.",
        "reasoning_content": "Let me compute 17 * 23. 17 * 20 = 340, 17 * 3 = 51, so 340 + 51 = 391."
      },
      "finish_reason": "stop",
      "index": 0
    }
  ]
}
```

### Responses API

Responses API trả về suy luận dưới dạng một mục đầu ra `reasoning` riêng biệt, đứng trước mục `message`.

```python
response = client.responses.create(
    model="Qwen/Qwen3-1.7B",
    input="What is 17 * 23?",
    stream=False,
)
reasoning_item = next(i for i in response.output if i.type == "reasoning")
message_item = next(i for i in response.output if i.type == "message")
print("reasoning:", reasoning_item.content[0].text)
print("answer:", message_item.content[0].text)
```

Streaming mở mục suy luận trước và phát các sự kiện `response.reasoning_text.delta`, sau đó đóng mục đó và mở mục tin nhắn để phát các sự kiện `response.output_text.delta`.

```python
stream = client.responses.create(
    model="Qwen/Qwen3-1.7B",
    input="What is 17 * 23?",
    stream=True,
)

for event in stream:
    if event.type == "response.reasoning_text.delta":
        print(event.delta, end="")
    elif event.type == "response.output_text.delta":
        print(event.delta, end="")
```

### Đi và về nhiều lượt

Đối với các cuộc trò chuyện nhiều lượt, hãy bao gồm văn bản suy luận từ phản hồi trước đó trong yêu cầu tiếp theo. Máy chủ sẽ truyền nó cho mẫu trò chuyện, cho phép hiển thị nó như một phần của lượt trợ lý trước đó để mô hình có thể nhìn thấy quá trình suy nghĩ trước đó của chính nó.

Gắn `reasoning_content` vào thông điệp trợ lý trước đó.

```python
first = client.chat.completions.create(
    model="Qwen/Qwen3-1.7B",
    messages=[{"role": "user", "content": "What is 17 * 23?"}],
).choices[0].message

second = client.chat.completions.create(
    model="Qwen/Qwen3-1.7B",
    messages=[
        {"role": "user", "content": "What is 17 * 23?"},
        {
            "role": "assistant",
            "content": first.content,
            "reasoning_content": first.reasoning_content,
        },
        {"role": "user", "content": "Now multiply that result by 2."},
    ],
)
print(second.choices[0].message.content)
```

Truyền mục `reasoning` trước đó lại như một mục đầu vào trước thông điệp của trợ lý.

```python
first = client.responses.create(
    model="Qwen/Qwen3-1.7B",
    input="What is 17 * 23?",
    stream=False,
)
reasoning_item = next(i for i in first.output if i.type == "reasoning")
message_item = next(i for i in first.output if i.type == "message")

second = client.responses.create(
    model="Qwen/Qwen3-1.7B",
    input=[
        {"role": "user", "content": "What is 17 * 23?"},
        reasoning_item.model_dump(exclude_none=True),
        {"role": "assistant", "content": message_item.content[0].text},
        {"role": "user", "content": "Now multiply that result by 2."},
    ],
    stream=False,
)
print(second.output_text)
```

## Chuyển tiếp cổng

Port forwarding cho phép bạn cung cấp các mô hình từ một máy chủ từ xa. Hãy đảm bảo bạn có quyền truy cập SSH vào máy chủ, sau đó chạy lệnh này trên máy cục bộ của bạn.

```bash
ssh -N -f -L 8000:localhost:8000 your_server_account@your_server_IP -p port_to_ssh_into_your_server
```

## Tính khả tái lập

Truyền model như một đối số vị trí để tránh các gợi ý model cho từng yêu cầu và tạo ra các lần chạy ổn định, có thể lặp lại.

```sh
transformers serve Qwen/Qwen2.5-0.5B-Instruct \
  --continuous-batching \
  --dtype "bfloat16"
```

