docs: add fine-tuning, assistants, configuration, error-handling, and response-types guides

Author: agentscope-ai-java

README.md

@@ -118,6 +118,8 @@ else:
         print(response.output.choices[0].message.content)
 ```
 
+For the full list of exception classes and when each is raised, see the [Error Handling Reference](docs/guides/error-handling.md).
+
 ## API Key Authentication
 
 The SDK uses API key for authentication. To obtain an API Key, see [How to get an API Key](https://help.aliyun.com/en/model-studio/get-api-key). Please refer to [official documentation for alibabacloud china](https://www.alibabacloud.com/help/en/model-studio/) and [official documentation for alibabacloud international](https://www.alibabacloud.com/help/en/model-studio/) regarding how to obtain your api-key.
@@ -252,6 +254,8 @@ print(response)
 
 A complete runnable example is available in [`samples/set_region_example.py`](samples/set_region_example.py).
 
+For request timeouts, custom headers, proxy support, and closing shared connection pools, see the [Advanced Configuration guide](docs/guides/configuration.md).
+
 ## AI Assistant: DashScope SDK Expert
 
 The SDK ships with an interactive AI assistant, **DashScope SDK Expert**, built on the bundled Agentic CLI (`dashscope/acli`) framework. For DashScope SDK/CLI users it is the recommended way to get development consultation and AI coding help — answering SDK/API questions, generating runnable examples, showing CLI usage, and diagnosing errors, right in your terminal.
@@ -297,6 +301,26 @@ response = MultiModalConversation.call(model="qwen-vl-max", messages=messages)
 print(response.output.choices[0].message.content[0]["text"])
 ```
 
+Use `AioMultiModalConversation` for the `async`/`await` form:
+
+```python
+import asyncio
+from dashscope import AioMultiModalConversation
+
+async def main():
+    messages = [{
+        "role": "user",
+        "content": [
+            {"image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241022/emyrja/dog_and_girl.jpeg"},
+            {"text": "What does this picture describe?"},
+        ],
+    }]
+    response = await AioMultiModalConversation.call(model="qwen-vl-max", messages=messages)
+    print(response.output.choices[0].message.content[0]["text"])
+
+asyncio.run(main())
+```
+
 ### Using Local Files
 
 Every field that accepts a URL (`image`, `audio`, `video` in messages; `images` on `ImageSynthesis`, etc.) also accepts a local file path — the SDK uploads it to OSS automatically, no manual header needed:
@@ -341,6 +365,22 @@ resp = MultiModalEmbedding.call(
 print(resp.output)
 ```
 
+### Batch (Offline) Text Embedding
+
+For large volumes of text, submit a file (one text per line) for asynchronous batch embedding instead of calling `TextEmbedding.call` per item:
+
+```python
+from dashscope import BatchTextEmbedding
+
+resp = BatchTextEmbedding.call(
+    model=BatchTextEmbedding.Models.text_embedding_async_v2,
+    url="https://example.com/texts.txt",
+)
+print(resp.output.task_id, resp.output.task_status)
+if resp.output.task_status == "SUCCEEDED":
+    print(resp.output.url)  # download the result file from here
+```
+
 ### Text ReRank
 
 ```python
@@ -360,6 +400,26 @@ for r in resp.output.results:
     print(r.index, r.relevance_score, r.document)
 ```
 
+Use `AioTextReRank` for the `async`/`await` form:
+
+```python
+import asyncio
+from dashscope import AioTextReRank
+
+async def main():
+    resp = await AioTextReRank.call(
+        model=AioTextReRank.Models.gte_rerank,
+        query="What is the capital of China?",
+        documents=["The capital of China is Beijing.", "China is a large country in East Asia."],
+        return_documents=True,
+        top_n=1,
+    )
+    for r in resp.output.results:
+        print(r.index, r.relevance_score, r.document)
+
+asyncio.run(main())
+```
+
 ### Code Generation
 
 `CodeGeneration` powers task-specific coding scenarios (`Scenes`): natural-language-to-code, code explanation, comment generation, commit messages, unit tests, code Q&A, and natural-language-to-SQL.
@@ -443,6 +503,21 @@ with open("output.wav", "wb") as f:
     f.write(result.get_audio_data())
 ```
 
+`HttpSpeechSynthesizer` calls TTS over plain HTTP (no WebSocket), useful in environments that can't hold a persistent connection:
+
+```python
+from dashscope.audio.http_tts import HttpSpeechSynthesizer
+
+result = HttpSpeechSynthesizer.call(
+    model="cosyvoice-v3-flash",
+    text="Hello, Bailian.",
+    voice="longxiaochun",
+    audio_format="wav",
+)
+with open("output.wav", "wb") as f:
+    f.write(result.audio_data)
+```
+
 ### Streaming Speech Synthesis (CosyVoice v2)
 
 Stream text in incrementally and receive audio bytes as they're generated, via a callback:
@@ -611,6 +686,12 @@ status = Deployments.get(deployed_model).output.status
 response = Generation.call(model=deployed_model, messages=[{"role": "user", "content": "Hi"}])
 ```
 
+For the full job/deployment lifecycle (listing, canceling, streaming events, scaling), see the [Fine-tuning & Deployment Lifecycle guide](docs/guides/fine-tuning.md).
+
+### Assistants API (Deprecated)
+
+The legacy Assistants API (`Assistants`, `Threads`, `Runs`, `Messages`) still works but is deprecated — see the [Assistants API guide](docs/guides/assistants.md) for the full surface and migration notes. New code should use [`Generation`](#quick-start) or [`MultiModalConversation`](#multimodal-understanding-vision) instead.
+
 ## CLI Usage
 
 Every SDK capability is also available as a `dashscope` sub-command (installed with the base package), for scripting or quick checks without writing Python:
@@ -676,5 +757,7 @@ response.output        # Any: the request output (shape depends on the API calle
 response.usage         # Any: token/quota usage information
 ```
 
+For how `output`/`usage` support both dict-style and attribute-style access, and the per-capability response subclasses, see the [Response Object Model guide](docs/guides/response-types.md).
+
 ## License
 This project is licensed under the Apache License (Version 2.0).

docs/guides/assistants.md

@@ -0,0 +1,104 @@
+# Assistants API (Deprecated)
+
+> **English** | [中文](assistants_zh.md) | [日本語](assistants_ja.md)
+
+> **Deprecated.** The Assistants API (`dashscope.assistants` and `dashscope.threads`) is deprecated and will be removed in a future release. Please migrate to [`Generation`](../../README.md#quick-start) or [`MultiModalConversation`](../../README.md#multimodal-understanding-vision) with the `messages` parameter. See the [migration reference](https://help.aliyun.com/zh/model-studio/synchronous-call-api-reference) for details.
+
+This guide documents the existing surface for maintaining code that still depends on it.
+
+## Basic Flow
+
+Create an assistant, start a thread, run it, and wait for completion:
+
+```python
+from dashscope import Assistants, Threads, Runs, Messages
+
+assistant = Assistants.create(
+    model="qwen-max",
+    name="smart helper",
+    description="A tool helper.",
+    instructions="You are a helpful assistant.",
+)
+
+thread = Threads.create(
+    messages=[{"role": "user", "content": "How do I make beef stew?"}],
+)
+
+run = Runs.create(thread.id, assistant_id=assistant.id)
+run_status = Runs.wait(run.id, thread_id=thread.id)
+print(run_status.status)
+
+messages = Messages.list(thread.id)
+print(messages)
+```
+
+## Assistants
+
+```python
+from dashscope import Assistants
+
+assistant = Assistants.get(assistant_id=assistant.id)
+
+assistants = Assistants.list(limit=20)
+for a in assistants.data:
+    print(a.id, a.name)
+
+assistant = Assistants.update(assistant.id, name="renamed helper")
+
+Assistants.delete(assistant.id)
+```
+
+## Threads
+
+```python
+from dashscope import Threads
+
+thread = Threads.get(thread_id=thread.id)
+thread = Threads.update(thread.id, metadata={"topic": "cooking"})
+Threads.delete(thread.id)
+```
+
+## Messages
+
+```python
+from dashscope import Messages
+
+message = Messages.create(thread.id, content="What about a vegetarian version?")
+message = Messages.get(message.id, thread_id=thread.id)
+messages = Messages.list(thread.id, limit=20)
+```
+
+## Runs
+
+```python
+from dashscope import Runs
+
+run = Runs.get(run.id, thread_id=thread.id)
+run = Runs.wait(run.id, thread_id=thread.id, timeout_seconds=60)
+Runs.cancel(run.id, thread_id=thread.id)
+```
+
+## Run Steps
+
+List the individual execution steps of a run (tool calls, message creations, etc.):
+
+```python
+from dashscope import Steps
+
+steps = Steps.list(run.id, thread_id=thread.id, limit=20)
+for step in steps.data:
+    print(step.id, step.type, step.status)
+```
+
+## Attaching Files to an Assistant
+
+Attaching a file uses a separate `Files` class under `dashscope.assistants` (distinct from the top-level `dashscope.Files` used for fine-tuning uploads):
+
+```python
+from dashscope.assistants.files import Files
+
+attached = Files.create(assistant_id=assistant.id, file_id="file-id-xxxx")
+print(attached)
+
+info = Files.get(assistant_id=assistant.id, file_id="file-id-xxxx")
+```

docs/guides/assistants_ja.md

@@ -0,0 +1,104 @@
+# Assistants API（非推奨）
+
+> [English](assistants.md) | [中文](assistants_zh.md) | **日本語**
+
+> **非推奨。** Assistants API（`dashscope.assistants` および `dashscope.threads`）は非推奨であり、将来のリリースで削除される予定です。`messages` パラメータを使用する [`Generation`](../../README_ja.md#クイックスタート) または [`MultiModalConversation`](../../README_ja.md#マルチモーダル理解ビジョン) への移行をお願いします。詳細は[移行リファレンス](https://help.aliyun.com/zh/model-studio/synchronous-call-api-reference)を参照してください。
+
+このガイドは、このAPIに依存するコードを保守するために、既存のインターフェースをまとめたものです。
+
+## 基本的な流れ
+
+アシスタントを作成し、スレッドを開始して実行し、完了を待ちます：
+
+```python
+from dashscope import Assistants, Threads, Runs, Messages
+
+assistant = Assistants.create(
+    model="qwen-max",
+    name="smart helper",
+    description="A tool helper.",
+    instructions="You are a helpful assistant.",
+)
+
+thread = Threads.create(
+    messages=[{"role": "user", "content": "How do I make beef stew?"}],
+)
+
+run = Runs.create(thread.id, assistant_id=assistant.id)
+run_status = Runs.wait(run.id, thread_id=thread.id)
+print(run_status.status)
+
+messages = Messages.list(thread.id)
+print(messages)
+```
+
+## Assistants
+
+```python
+from dashscope import Assistants
+
+assistant = Assistants.get(assistant_id=assistant.id)
+
+assistants = Assistants.list(limit=20)
+for a in assistants.data:
+    print(a.id, a.name)
+
+assistant = Assistants.update(assistant.id, name="renamed helper")
+
+Assistants.delete(assistant.id)
+```
+
+## Threads
+
+```python
+from dashscope import Threads
+
+thread = Threads.get(thread_id=thread.id)
+thread = Threads.update(thread.id, metadata={"topic": "cooking"})
+Threads.delete(thread.id)
+```
+
+## Messages
+
+```python
+from dashscope import Messages
+
+message = Messages.create(thread.id, content="What about a vegetarian version?")
+message = Messages.get(message.id, thread_id=thread.id)
+messages = Messages.list(thread.id, limit=20)
+```
+
+## Runs
+
+```python
+from dashscope import Runs
+
+run = Runs.get(run.id, thread_id=thread.id)
+run = Runs.wait(run.id, thread_id=thread.id, timeout_seconds=60)
+Runs.cancel(run.id, thread_id=thread.id)
+```
+
+## Run Steps
+
+run の個々の実行ステップ（ツール呼び出し、メッセージ作成など）を一覧表示します：
+
+```python
+from dashscope import Steps
+
+steps = Steps.list(run.id, thread_id=thread.id, limit=20)
+for step in steps.data:
+    print(step.id, step.type, step.status)
+```
+
+## アシスタントへのファイルの添付
+
+ファイルの添付には、`dashscope.assistants` 配下の専用の `Files` クラスを使用します（微調整のアップロードに使うトップレベルの `dashscope.Files` とは別のものです）：
+
+```python
+from dashscope.assistants.files import Files
+
+attached = Files.create(assistant_id=assistant.id, file_id="file-id-xxxx")
+print(attached)
+
+info = Files.get(assistant_id=assistant.id, file_id="file-id-xxxx")
+```