From f823b4250affebc64bab46859b97d3a99b583161 Mon Sep 17 00:00:00 2001 From: "zhansheng.lzs" Date: Mon, 16 Nov 2026 14:45:23 +0800 Subject: [PATCH 01/19] perf(tokenizers): exclude qwen.tiktoken from wheel, download on demand The 2.4MB vocab no longer ships in distributions; get_tokenizer() resolves it from DASHSCOPE_QWEN_VOCAB, the source tree, or a SHA256-verified ModelScope download cached under ~/.cache/dashscope/tokenizers. --- MANIFEST.in | 2 +- dashscope/legacy_1x/tokenizers/tokenizer.py | 83 ++++++++++++++++++++- 2 files changed, 81 insertions(+), 4 deletions(-) diff --git a/MANIFEST.in b/MANIFEST.in index 3d855be6..6d920e6a 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,4 +1,4 @@ -include dashscope/legacy_1x/tokenizers/qwen.tiktoken +exclude dashscope/legacy_1x/tokenizers/qwen.tiktoken include dashscope/py.typed include dashscope/__init__.pyi include NOTICE diff --git a/dashscope/legacy_1x/tokenizers/tokenizer.py b/dashscope/legacy_1x/tokenizers/tokenizer.py index eb8d128a..6f772c30 100644 --- a/dashscope/legacy_1x/tokenizers/tokenizer.py +++ b/dashscope/legacy_1x/tokenizers/tokenizer.py @@ -1,7 +1,10 @@ # -*- coding: utf-8 -*- # Copyright (c) Alibaba, Inc. and its affiliates. +import hashlib import os +import tempfile +import urllib.request from typing import List from dashscope.legacy_1x.common.error import UnsupportedModel @@ -9,16 +12,90 @@ from .tokenizer_base import Tokenizer QWEN_SERIALS = ["qwen-7b-chat", "qwen-turbo", "qwen-plus", "qwen-max"] -# The vocab ships next to this module, so the leaf stays relocatable. +_VOCAB_NAME = "qwen.tiktoken" +# The vocab ships next to this module in source checkouts, but is excluded +# from wheels (MANIFEST.in); installed packages download it on first use. _VOCAB_PATH = os.path.join( os.path.dirname(os.path.abspath(__file__)), - "qwen.tiktoken", + _VOCAB_NAME, ) +_VOCAB_URL = ( + "https://www.modelscope.cn/models/Qwen/Qwen-7B-Chat/resolve/master/" + + _VOCAB_NAME +) +_VOCAB_SHA256 = ( + "b2b1b8dfb5cc5f024bafc373121c6aba3f66f9a5a0269e243470a1de16a33186" +) +_VOCAB_CACHE_DIR = os.path.join( + os.path.expanduser("~"), + ".cache", + "dashscope", + "tokenizers", +) +_VOCAB_ENV = "DASHSCOPE_QWEN_VOCAB" + + +def _sha256(path: str) -> str: + digest = hashlib.sha256() + with open(path, "rb") as f: + for chunk in iter(lambda: f.read(1 << 20), b""): + digest.update(chunk) + return digest.hexdigest() + + +def _download_vocab(dest: str) -> None: + os.makedirs(os.path.dirname(dest), exist_ok=True) + fd, tmp = tempfile.mkstemp( + dir=os.path.dirname(dest), + prefix=_VOCAB_NAME + ".", + suffix=".download", + ) + os.close(fd) + try: + with urllib.request.urlopen(_VOCAB_URL, timeout=60) as resp: + with open(tmp, "wb") as f: + while True: + chunk = resp.read(1 << 20) + if not chunk: + break + f.write(chunk) + if _sha256(tmp) != _VOCAB_SHA256: + raise IOError( + f"SHA256 mismatch for vocab downloaded from {_VOCAB_URL}", + ) + os.replace(tmp, dest) + except Exception as exc: + raise RuntimeError( + f"Failed to obtain the Qwen tokenizer vocab ({_VOCAB_NAME}). " + f"Download it manually from {_VOCAB_URL} and either place it " + f"at {dest} or point {_VOCAB_ENV} at the file " + f"(required for offline environments). Cause: {exc}", + ) from exc + finally: + if os.path.exists(tmp): + os.unlink(tmp) + + +def _resolve_vocab_path() -> str: + override = os.environ.get(_VOCAB_ENV) + if override: + return os.path.expanduser(override) + if os.path.isfile(_VOCAB_PATH): + return _VOCAB_PATH + cached = os.path.join(_VOCAB_CACHE_DIR, _VOCAB_NAME) + if os.path.isfile(cached) and _sha256(cached) == _VOCAB_SHA256: + return cached + _download_vocab(cached) + return cached def get_tokenizer(model: str) -> Tokenizer: """Get a tokenizer based on model name. + The vocab file ships with source checkouts; installed wheels download + it on first use from ModelScope into ``~/.cache/dashscope/tokenizers``. + Set ``DASHSCOPE_QWEN_VOCAB`` to a local file path for offline use. + Args: model (str): The model name. @@ -29,7 +106,7 @@ def get_tokenizer(model: str) -> Tokenizer: Tokenizer: The `Tokenizer` of the model. """ if model.startswith("qwen"): - return QwenTokenizer(_VOCAB_PATH) + return QwenTokenizer(_resolve_vocab_path()) raise UnsupportedModel( f"Not support model: {model}, currently only support qwen models.", ) From 33e6ed9c062b6b30259aeba6a1993cc3b462a0f6 Mon Sep 17 00:00:00 2001 From: "zhansheng.lzs" Date: Mon, 16 Nov 2026 15:17:04 +0800 Subject: [PATCH 02/19] fix(audio): detach socket inside the error-processing lock hold The receive path used to drop the state lock when event processing raised, then re-acquire it in the outer handler to detach the socket. A concurrent send_event could slip that gap and write to a socket that was about to be closed. Detach within the same lock hold instead, and add witness-thread regression tests that reproduce the race deterministically (they fail on the previous code). --- dashscope/resources/audio/live.py | 129 ++++++++++++++------------ dashscope/resources/audio/realtime.py | 124 ++++++++++++++----------- tests/test_audio_live_session.py | 95 +++++++++++++++++++ tests/test_audio_tts_realtime.py | 108 ++++++++++++++++++++- 4 files changed, 342 insertions(+), 114 deletions(-) diff --git a/dashscope/resources/audio/live.py b/dashscope/resources/audio/live.py index d6597da4..55ab7541 100644 --- a/dashscope/resources/audio/live.py +++ b/dashscope/resources/audio/live.py @@ -293,73 +293,84 @@ def _recv_event( # pylint: disable=too-many-return-statements if ws is not self._ws: self._check_unfinished() return None - if raw is None or raw == "" or raw == b"": - raise APIConnectionError( - "live websocket disconnected before session.closed", - ) try: - if isinstance(raw, (bytes, bytearray)): - raw = raw.decode("utf-8") - event = json.loads(raw) - except (ValueError, TypeError) as exc: - raise WsEventError( - "expected a UTF-8 JSON event object", - body=raw, - ) from exc - if not isinstance(event, dict): - raise WsEventError( - "expected a JSON event object", - body=event, - ) - if ( - not isinstance(event.get("type"), str) - or not event["type"] - ): - raise WsEventError( - "expected a non-empty string event type", - body=event, - ) - self.last_message = event - self._track_event(event) - if event["type"] == EVENT_SESSION_CLOSED: - self._finished = True - closing_ws = self._detach_socket() - self._check_unfinished() - elif event["type"] == EVENT_ERROR: - error = event.get("error") - if error is None: - error = {} - if not isinstance(error, dict): + if raw is None or raw == "" or raw == b"": + raise APIConnectionError( + "live websocket disconnected before session.closed", + ) + try: + if isinstance(raw, (bytes, bytearray)): + raw = raw.decode("utf-8") + event = json.loads(raw) + except (ValueError, TypeError) as exc: raise WsEventError( - "expected a JSON error object", + "expected a UTF-8 JSON event object", + body=raw, + ) from exc + if not isinstance(event, dict): + raise WsEventError( + "expected a JSON event object", body=event, ) - code = error.get("code") - if code is None or code == "": - code = event.get("code") - if code is not None and not isinstance(code, str): + if ( + not isinstance(event.get("type"), str) + or not event["type"] + ): raise WsEventError( - "expected a string error code", + "expected a non-empty string event type", + body=event, + ) + self.last_message = event + self._track_event(event) + if event["type"] == EVENT_SESSION_CLOSED: + self._finished = True + closing_ws = self._detach_socket() + self._check_unfinished() + elif event["type"] == EVENT_ERROR: + error = event.get("error") + if error is None: + error = {} + if not isinstance(error, dict): + raise WsEventError( + "expected a JSON error object", + body=event, + ) + code = error.get("code") + if code is None or code == "": + code = event.get("code") + if code is not None and not isinstance(code, str): + raise WsEventError( + "expected a string error code", + body=event, + ) + failure = error_from_business_code( + message=error.get("message") or "live error", + code=code, body=event, ) - failure = error_from_business_code( - message=error.get("message") or "live error", - code=code, - body=event, - ) - failure.status_code = None - recoverable = ( - error.get("type") == "invalid_request_error" - ) - if recoverable: - if self._finish_event_id is not None and ( - error.get("event_id") == self._finish_event_id - ): - self._finish_requested = False - self._finish_event_id = None - else: - self._failure = failure + failure.status_code = None + recoverable = ( + error.get("type") == "invalid_request_error" + ) + if recoverable: + if self._finish_event_id is not None and ( + error.get("event_id") + == self._finish_event_id + ): + self._finish_requested = False + self._finish_event_id = None + else: + self._failure = failure + closing_ws = self._detach_socket() + except BaseException as exc: + # Detach within the same state-lock hold so a concurrent + # send observes the closed session instead of racing the + # cleanup into _send_raw (lock inversion). + if ws is self._ws and generation == self._generation: + if isinstance(exc, DashScopeError): + self._failure = exc closing_ws = self._detach_socket() + raise except BaseException as exc: with self._lock: if ws is self._ws and generation == self._generation: diff --git a/dashscope/resources/audio/realtime.py b/dashscope/resources/audio/realtime.py index d3bbfc80..2eb55688 100644 --- a/dashscope/resources/audio/realtime.py +++ b/dashscope/resources/audio/realtime.py @@ -676,61 +676,77 @@ def recv_event(self) -> Optional[Dict[str, Any]]: self._check_unfinished() return None received_on_current_connection = True - if raw is None or raw == "" or raw == b"": - closing_ws = self._detach_socket() - self._check_unfinished() - _logger.debug( - "Realtime connection closed, request_id=%s", - self._request_id_for_log(), - ) - return None - if isinstance(raw, (bytes, bytearray)): - raw = raw.decode("utf-8") - event = json.loads(raw) - if not isinstance(event, dict): - raise ValueError("expected a JSON event object") - self.last_message = event - self._track_event(event) - if event.get("type") == "session.finished": - self._finished = True - closing_ws = self._detach_socket() - self._check_unfinished() - elif event.get("type") == "error": - error = event.get("error") - if error is None: - error = {} - if not isinstance(error, dict): - raise ValueError("expected a JSON error object") - code = error.get("code") - if code is not None and not isinstance(code, str): - raise ValueError("expected a string error code") - failure = error_from_business_code( - message=error.get("message") or "realtime error", - code=code, - body=event, - ) - # Only real IDs belong on exceptions; protocol fallbacks - # and "unknown" are strictly logging context. - explicit_request_id = _event_request_id(event) - if explicit_request_id is not None: - failure.request_id = explicit_request_id - _logger.error( - "Realtime business error, request_id=%s", - self._request_id_for_log(), - ) - recoverable = ( - error.get("type") == "invalid_request_error" - ) - if recoverable: - # The nested event_id identifies the rejected request. - request_id = error.get("event_id") - if ( - isinstance(request_id, str) - and request_id in self._pending_response_ids - ): - self._pending_response_ids.remove(request_id) - if not recoverable or self._finish_requested: + try: + if raw is None or raw == "" or raw == b"": + closing_ws = self._detach_socket() + self._check_unfinished() + _logger.debug( + "Realtime connection closed, request_id=%s", + self._request_id_for_log(), + ) + return None + if isinstance(raw, (bytes, bytearray)): + raw = raw.decode("utf-8") + event = json.loads(raw) + if not isinstance(event, dict): + raise ValueError("expected a JSON event object") + self.last_message = event + self._track_event(event) + if event.get("type") == "session.finished": + self._finished = True + closing_ws = self._detach_socket() + self._check_unfinished() + elif event.get("type") == "error": + error = event.get("error") + if error is None: + error = {} + if not isinstance(error, dict): + raise ValueError( + "expected a JSON error object", + ) + code = error.get("code") + if code is not None and not isinstance(code, str): + raise ValueError( + "expected a string error code", + ) + failure = error_from_business_code( + message=error.get("message") + or "realtime error", + code=code, + body=event, + ) + # Only real IDs belong on exceptions; protocol fallbacks + # and "unknown" are strictly logging context. + explicit_request_id = _event_request_id(event) + if explicit_request_id is not None: + failure.request_id = explicit_request_id + _logger.error( + "Realtime business error, request_id=%s", + self._request_id_for_log(), + ) + recoverable = ( + error.get("type") == "invalid_request_error" + ) + if recoverable: + # The nested event_id identifies the rejected request. + request_id = error.get("event_id") + if ( + isinstance(request_id, str) + and request_id + in self._pending_response_ids + ): + self._pending_response_ids.remove( + request_id, + ) + if not recoverable or self._finish_requested: + closing_ws = self._detach_socket() + except BaseException: + # Detach within the same state-lock hold so a concurrent + # send observes the closed session instead of racing the + # cleanup into _send_raw (lock inversion). + if ws is self._ws and generation == self._generation: closing_ws = self._detach_socket() + raise except BaseException as exc: with self._lock: if generation == self._generation and ( diff --git a/tests/test_audio_live_session.py b/tests/test_audio_live_session.py index 73135410..407616a4 100644 --- a/tests/test_audio_live_session.py +++ b/tests/test_audio_live_session.py @@ -826,6 +826,101 @@ def test_events_raises_fatal_errors_instead_of_yielding_them(opened): session.recv_event() +def test_error_cleanup_completes_before_a_queued_send_can_observe_the_session( + opened, +): + # A send queued on the state lock must never observe a still-attached + # socket after a fatal receive error: cleanup has to finish before the + # receive path drops the lock, or the send races it into _send_raw. + session, ws = opened + gate = threading.Event() + resume = threading.Event() + blocked = threading.Event() + queued = threading.Event() + exit_unlocked = threading.Event() + processing_error = [] + sender_errors = [] + lock = session._lock + + class ObservedLock: + def __enter__(self): + if threading.current_thread().name == "witness-send": + queued.set() + return lock.__enter__() + + def __exit__(self, *args): + result = lock.__exit__(*args) + if processing_error: + # Widen the post-error unlock window deterministically: the + # queued sender must get the lock before any further cleanup. + processing_error.clear() + exit_unlocked.set() + assert resume.wait(5) + return result + + original_track = session._track_event + + def gated_track(event): + original_track(event) + if event.get("type") == "error": + processing_error.append(True) + blocked.set() + assert gate.wait(5) + + session._lock = ObservedLock() + session._track_event = gated_track + ws.inbox.append( + { + "type": "error", + # A non-dict error object raises WsEventError after _track_event, + # exercising the exception cleanup path (not the business-error + # branch, which already detached under the lock before the fix). + "error": "boom", + }, + ) + + def send(): + try: + session.send_event({"type": "input_audio_buffer.append"}) + except BaseException as exc: # noqa: BLE001 - record any outcome + sender_errors.append(exc) + + sender = threading.Thread(target=send, name="witness-send", daemon=True) + receiver_errors = [] + + def receive(): + try: + session.recv_event() + except BaseException as exc: # noqa: BLE001 - record any outcome + receiver_errors.append(exc) + + receiver = threading.Thread(target=receive, daemon=True) + receiver.start() + try: + assert blocked.wait(5) + sender.start() + assert queued.wait(5) + gate.set() + assert exit_unlocked.wait(5) + resume.set() + sender.join(5) + receiver.join(5) + assert not sender.is_alive() + assert not receiver.is_alive() + assert len(receiver_errors) == 1 + assert isinstance(receiver_errors[0], DashScopeError) + assert len(sender_errors) == 1 + assert isinstance(sender_errors[0], RuntimeError) + assert "not open" in str(sender_errors[0]) + assert ws.sent == [] + assert session._ws is None + finally: + gate.set() + resume.set() + sender.join(3) + receiver.join(3) + + def test_websocket_business_errors_have_no_invented_http_status(opened): session, ws = opened ws.inbox.append( diff --git a/tests/test_audio_tts_realtime.py b/tests/test_audio_tts_realtime.py index 6ee5723f..3d161cad 100644 --- a/tests/test_audio_tts_realtime.py +++ b/tests/test_audio_tts_realtime.py @@ -9,6 +9,7 @@ import json import logging +import threading import pytest from websocket import ( @@ -481,6 +482,112 @@ def test_realtime_error_event_maps_wire_code(): assert error.status_code == 200 +def test_realtime_error_cleanup_completes_before_a_queued_send_can_observe(): + # A send queued on the state lock must never observe a still-attached + # socket after a fatal receive error: cleanup has to finish before the + # receive path drops the lock, or the send races it into _send_raw. + ws = FakeWebSocket( + [ + json.dumps( + { + "type": "error", + # A non-string code raises ValueError after _track_event, + # exercising the exception cleanup path (not the + # business-error branch, which already detached under + # the lock before the fix). + "error": {"code": 123, "message": "gone"}, + }, + ), + ], + ) + client = _make_client() + with client.audio.realtime.connect( + model="qwen-omni-turbo-realtime", + connector=lambda url, headers: ws, + ) as rt: + gate = threading.Event() + resume = threading.Event() + blocked = threading.Event() + queued = threading.Event() + exit_unlocked = threading.Event() + processing_error = [] + sender_errors = [] + lock = rt._lock + + class ObservedLock: + def __enter__(self): + if threading.current_thread().name == "witness-send": + queued.set() + return lock.__enter__() + + def __exit__(self, *args): + lock.__exit__(*args) + if processing_error: + # Widen the post-error unlock window deterministically: + # the queued sender must get the lock before any further + # cleanup. + processing_error.clear() + exit_unlocked.set() + assert resume.wait(5) + + original_track = rt._track_event + + def gated_track(event): + original_track(event) + if event.get("type") == "error": + processing_error.append(True) + blocked.set() + assert gate.wait(5) + + rt._lock = ObservedLock() + rt._track_event = gated_track + + def send(): + try: + rt.send_event({"type": "input_audio_buffer.append"}) + except BaseException as exc: # noqa: BLE001 - record any outcome + sender_errors.append(exc) + + sender = threading.Thread( + target=send, + name="witness-send", + daemon=True, + ) + receiver_errors = [] + + def receive(): + try: + rt.recv_event() + except BaseException as exc: # noqa: BLE001 - record any outcome + receiver_errors.append(exc) + + receiver = threading.Thread(target=receive, daemon=True) + receiver.start() + try: + assert blocked.wait(5) + sender.start() + assert queued.wait(5) + gate.set() + assert exit_unlocked.wait(5) + resume.set() + sender.join(5) + receiver.join(5) + assert not sender.is_alive() + assert not receiver.is_alive() + assert len(receiver_errors) == 1 + assert isinstance(receiver_errors[0], ValueError) + assert len(sender_errors) == 1 + assert isinstance(sender_errors[0], RuntimeError) + assert "not open" in str(sender_errors[0]) + assert ws.sent == [] + assert rt._ws is None + finally: + gate.set() + resume.set() + sender.join(3) + receiver.join(3) + + def test_realtime_send_requires_open_session(): client = _make_client() session = client.audio.realtime.connect(model="qwen-omni-turbo-realtime") @@ -897,7 +1004,6 @@ def test_realtime_retired_reader_does_not_log_current_request_errors( monkeypatch, reconnect, ): - import threading from concurrent.futures import ThreadPoolExecutor caplog.set_level(logging.ERROR, logger=_REALTIME_LOGGER) From 94a32ee4dbdf674262af690e8ab5de63cd095510 Mon Sep 17 00:00:00 2001 From: luk384090-cloud Date: Mon, 16 Nov 2026 15:35:31 +0800 Subject: [PATCH 03/19] build(ci): add multi-platform CLI binary build workflow - Introduce pyproject.toml with setuptools build system configuration - Update .gitignore to ignore *.pyd files for Windows builds - Modify release.yml to separate Python package build and native CLI binary builds - Implement build matrix for macOS (Apple Silicon and Intel), Linux, and Windows platforms - Use PyInstaller to create standalone dashscope CLI executables per platform - Add checksum generation for Python distributions and CLI binaries - Add smoke tests for built binaries to verify version command - Upload Python distributions and platform-specific CLI tarballs as separate artifacts - Adjust PyPI publishing step to upload only Python wheel and source distribution - Consolidate all release files in artifacts/ directory and update release notes files accordingly --- .github/workflows/release.yml | 91 ++++++++++++++++++++++++++++++++--- .gitignore | 1 + pyproject.toml | 12 +++++ 3 files changed, 96 insertions(+), 8 deletions(-) create mode 100644 pyproject.toml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 256a0d4d..e3789085 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -42,14 +42,85 @@ jobs: with: python-version: '3.13' - run: python -m pip install build twine - - run: python -m build + # dashscope is pure Python, so `python -m build` emits ONE universal + # py3-none-any wheel plus the sdist. pip installs that single wheel on + # every platform (Linux, Windows, macOS, iOS, Android, ...); native + # multi-platform distribution of the CLI is the `build` job below. + - run: python -m build --outdir dist - run: twine check dist/* + - run: sha256sum dist/* > dist/SHA256SUMS-python - uses: actions/upload-artifact@v4 with: name: python-distribution + path: dist/* + + build: + needs: [validate] + name: Build CLI binary (${{ matrix.platform }}) + # Standalone `dashscope` CLI executables, one per desktop platform, built + # natively on each runner (no cross-compilation). Each OS builds its own + # arch: macos-latest is Apple Silicon, macos-15-intel is x86_64. + strategy: + fail-fast: false + matrix: + include: + - os: macos-latest + arch: arm64 + platform: macos-arm64 + executable: dashscope + - os: macos-15-intel + arch: x86_64 + platform: macos-x86_64 + executable: dashscope + - os: ubuntu-latest + arch: x86_64 + platform: linux-x86_64 + executable: dashscope + - os: windows-latest + arch: x86_64 + platform: windows-x86_64 + executable: dashscope.exe + runs-on: ${{ matrix.os }} + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + # Base CLI scope: the package plus PyInstaller only. The optional + # acli/voice/camera extras (incl. the AgenticX agent) are intentionally + # NOT bundled, so the bare-`dashscope` agent path is unavailable in the + # binary by design; the v2 command tree is what ships. + - run: python -m pip install . "pyinstaller>=6.0" + - name: Build binary + run: | + pyinstaller \ + --onefile \ + --name ${{ matrix.executable }} \ + --collect-all dashscope \ + --collect-submodules dashscope.cli.commands \ + --clean \ + dashscope/cli/__main__.py + shell: bash + # `dashscope version` is the network-free v2 subcommand. There is no + # --version flag, and a bare `dashscope` would route to the (unbundled) + # agent, so the smoke test names the `version` command explicitly. + - name: Smoke test binary + run: ./dist/${{ matrix.executable }} version + shell: bash + - name: Package release asset + run: | + mkdir -p package/dashscope + cp "dist/${{ matrix.executable }}" package/dashscope/ + tar -czf "dist/dashscope-cli-${{ matrix.platform }}.tar.gz" \ + -C package dashscope + python -c 'import hashlib; from pathlib import Path; asset = Path("dist/dashscope-cli-${{ matrix.platform }}.tar.gz"); print(hashlib.sha256(asset.read_bytes()).hexdigest(), asset.name)' > "dist/SHA256SUMS-${{ matrix.platform }}" + shell: bash + - uses: actions/upload-artifact@v4 + with: + name: dashscope-cli-${{ matrix.platform }} path: | - dist/*.whl - dist/*.tar.gz + dist/dashscope-cli-${{ matrix.platform }}.tar.gz + dist/SHA256SUMS-${{ matrix.platform }} pypi: needs: [package] @@ -64,11 +135,14 @@ jobs: with: name: python-distribution path: dist/ + # PyPI accepts only the wheel + sdist; drop the checksum sidecar. + - name: Keep only Python distributions + run: rm dist/SHA256SUMS-python - name: Publish to PyPI uses: pypa/gh-action-pypi-publish@release/v1 release: - needs: [package] + needs: [build, package] runs-on: ubuntu-latest permissions: contents: write @@ -77,10 +151,11 @@ jobs: with: fetch-depth: 0 + # Collect every artifact: the Python distribution (wheel + sdist + + # checksums) and all four CLI binary tarballs, each under artifacts//. - uses: actions/download-artifact@v4 with: - name: python-distribution - path: dist/ + path: artifacts/ - name: Render release notes env: @@ -123,6 +198,6 @@ jobs: uses: softprops/action-gh-release@v2 with: body_path: release-body.md - files: dist/* + files: artifacts/**/* draft: true - prerelease: ${{ steps.prerelease.outputs.flag }} \ No newline at end of file + prerelease: ${{ steps.prerelease.outputs.flag }} diff --git a/.gitignore b/.gitignore index d819b762..5b36fd85 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ __pycache__/ # C extensions *.so +*.pyd # Distribution / packaging .Python diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 00000000..f0084c61 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,12 @@ +# Build configuration for dashscope. +# +# dashscope is a pure-Python package: ``python -m build`` emits ONE universal +# ``py3-none-any`` wheel plus an sdist, and pip installs that single wheel on +# every platform (Linux, Windows, macOS, iOS, Android, ...). There is no +# compiled extension and no cibuildwheel matrix. Native multi-platform +# distribution of the ``dashscope`` CLI is handled separately by PyInstaller +# binaries built in .github/workflows/release.yml. + +[build-system] +requires = ["setuptools>=61", "wheel"] +build-backend = "setuptools.build_meta" From 65b41f06d105cf69efe35e8d223e7d2dac426dba Mon Sep 17 00:00:00 2001 From: luk384090-cloud Date: Tue, 17 Nov 2026 11:01:18 +0800 Subject: [PATCH 04/19] docs(mkdocs): add MkDocs documentation site configuration and integration - Added mkdocs.yml with Material theme and multi-language support (English and Chinese) - Configured navigation tabs, search, and extra CSS for enhanced UI - Integrated plugins: search, i18n, autorefs, mkdocstrings with python handler - Setup documentation structure with nav entries for SDK features and references - Added docs/hooks.py to inject SDK version dynamically in documentation pages - Updated README.md and README_zh.md to reference the new documentation site URLs - Replaced Sphinx with MkDocs in requirements-doc.txt for documentation dependencies - Added GitHub Actions workflow (.github/workflows/docs.yml) for building and deploying docs - Removed obsolete Sphinx Makefile and make.bat scripts from docs directory --- .github/workflows/docs.yml | 64 +++ .gitignore | 3 - README.md | 2 + README_zh.md | 2 + dashscope/legacy_1x/aigc/conversation.py | 2 +- dashscope/legacy_1x/aigc/image_generation.py | 4 +- dashscope/legacy_1x/aigc/image_synthesis.py | 4 +- dashscope/legacy_1x/aigc/video_synthesis.py | 8 +- dashscope/legacy_1x/audio/asr/recognition.py | 6 +- .../audio/asr/translation_recognizer.py | 16 +- .../audio/http_tts/http_speech_synthesizer.py | 2 +- .../audio/qwen_tts/speech_synthesizer.py | 2 +- dashscope/legacy_1x/files.py | 2 +- dashscope/legacy_1x/finetune/deployments.py | 2 +- dashscope/legacy_1x/models.py | 3 +- .../legacy_1x/threads/messages/messages.py | 9 +- dashscope/legacy_1x/threads/runs/runs.py | 3 +- docs/Makefile | 20 - docs/README.md | 85 ++- docs/README_zh.md | 94 ++++ docs/assets/logo.svg | 4 + docs/en/about.md | 47 ++ docs/en/cli.md | 79 +++ docs/en/develop.md | 51 ++ docs/en/features.md | 96 ++++ docs/en/guides/qwen-live-python-sdk.md | 532 ++++++++++++++++++ docs/en/guides/recipes.md | 124 ++++ docs/en/index.md | 143 +++++ docs/en/migration.md | 89 +++ docs/en/quickstart.md | 147 +++++ docs/en/reference/agentic-rl.md | 57 ++ docs/en/reference/agentstudio.md | 243 ++++++++ docs/en/reference/audio.md | 82 +++ docs/en/reference/chat.md | 28 + docs/en/reference/client.md | 40 ++ docs/en/reference/devkit.md | 43 ++ docs/en/reference/errors.md | 58 ++ docs/en/reference/legacy.md | 183 ++++++ docs/en/reference/protocols.md | 33 ++ docs/en/reference/resources.md | 217 +++++++ docs/en/reference/types.md | 62 ++ docs/en/release-notes.md | 45 ++ docs/hooks.py | 28 + docs/make.bat | 35 -- docs/overrides/main.html | 17 + docs/source/_templates/autosummary/class.rst | 10 - docs/source/_templates/classtemplate.rst | 12 - docs/source/_templates/sobolengine.rst | 14 - docs/source/api/dashscope.aigc.rst | 15 - ...shscope.aigc.conversation.Conversation.rst | 13 - .../dashscope.aigc.conversation.History.rst | 13 - ...ashscope.aigc.conversation.HistoryItem.rst | 13 - docs/source/conf.py | 145 ----- docs/source/develop.md | 48 -- docs/source/index.rst | 26 - docs/stylesheets/extra.css | 43 ++ docs/zh/about.md | 42 ++ docs/zh/cli.md | 76 +++ docs/zh/develop.md | 50 ++ docs/zh/features.md | 93 +++ docs/{ => zh/guides}/qwen-live-python-sdk.md | 3 + docs/zh/guides/recipes.md | 123 ++++ docs/zh/index.md | 141 +++++ docs/zh/migration.md | 86 +++ docs/zh/quickstart.md | 142 +++++ docs/zh/reference/agentic-rl.md | 56 ++ docs/zh/reference/agentstudio.md | 242 ++++++++ docs/zh/reference/audio.md | 82 +++ docs/zh/reference/chat.md | 27 + docs/zh/reference/client.md | 39 ++ docs/zh/reference/devkit.md | 43 ++ docs/zh/reference/errors.md | 58 ++ docs/zh/reference/legacy.md | 181 ++++++ docs/zh/reference/protocols.md | 32 ++ docs/zh/reference/resources.md | 217 +++++++ docs/zh/reference/types.md | 61 ++ docs/zh/release-notes.md | 43 ++ mkdocs.yml | 172 ++++++ requirements-doc.txt | 17 +- setup.py | 5 + 80 files changed, 4783 insertions(+), 416 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 docs/Makefile create mode 100644 docs/README_zh.md create mode 100644 docs/assets/logo.svg create mode 100644 docs/en/about.md create mode 100644 docs/en/cli.md create mode 100644 docs/en/develop.md create mode 100644 docs/en/features.md create mode 100644 docs/en/guides/qwen-live-python-sdk.md create mode 100644 docs/en/guides/recipes.md create mode 100644 docs/en/index.md create mode 100644 docs/en/migration.md create mode 100644 docs/en/quickstart.md create mode 100644 docs/en/reference/agentic-rl.md create mode 100644 docs/en/reference/agentstudio.md create mode 100644 docs/en/reference/audio.md create mode 100644 docs/en/reference/chat.md create mode 100644 docs/en/reference/client.md create mode 100644 docs/en/reference/devkit.md create mode 100644 docs/en/reference/errors.md create mode 100644 docs/en/reference/legacy.md create mode 100644 docs/en/reference/protocols.md create mode 100644 docs/en/reference/resources.md create mode 100644 docs/en/reference/types.md create mode 100644 docs/en/release-notes.md create mode 100644 docs/hooks.py delete mode 100644 docs/make.bat create mode 100644 docs/overrides/main.html delete mode 100644 docs/source/_templates/autosummary/class.rst delete mode 100644 docs/source/_templates/classtemplate.rst delete mode 100644 docs/source/_templates/sobolengine.rst delete mode 100644 docs/source/api/dashscope.aigc.rst delete mode 100644 docs/source/api/generated/dashscope.aigc.conversation.Conversation.rst delete mode 100644 docs/source/api/generated/dashscope.aigc.conversation.History.rst delete mode 100644 docs/source/api/generated/dashscope.aigc.conversation.HistoryItem.rst delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/develop.md delete mode 100644 docs/source/index.rst create mode 100644 docs/stylesheets/extra.css create mode 100644 docs/zh/about.md create mode 100644 docs/zh/cli.md create mode 100644 docs/zh/develop.md create mode 100644 docs/zh/features.md rename docs/{ => zh/guides}/qwen-live-python-sdk.md (99%) create mode 100644 docs/zh/guides/recipes.md create mode 100644 docs/zh/index.md create mode 100644 docs/zh/migration.md create mode 100644 docs/zh/quickstart.md create mode 100644 docs/zh/reference/agentic-rl.md create mode 100644 docs/zh/reference/agentstudio.md create mode 100644 docs/zh/reference/audio.md create mode 100644 docs/zh/reference/chat.md create mode 100644 docs/zh/reference/client.md create mode 100644 docs/zh/reference/devkit.md create mode 100644 docs/zh/reference/errors.md create mode 100644 docs/zh/reference/legacy.md create mode 100644 docs/zh/reference/protocols.md create mode 100644 docs/zh/reference/resources.md create mode 100644 docs/zh/reference/types.md create mode 100644 docs/zh/release-notes.md create mode 100644 mkdocs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..158097b8 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,64 @@ +name: Docs + +# FastAPI-style docs pipeline: every PR and main push builds the MkDocs +# Material site to validate it; pushes to main additionally deploy the HTML +# to GitHub Pages. Docs track main (latest), independent of the tag-driven +# release.yml flow. +on: + push: + branches: [main] + paths: + - 'docs/**' + - 'dashscope/**' + - 'mkdocs.yml' + - 'requirements-doc.txt' + - '.github/workflows/docs.yml' + pull_request: + paths: + - 'docs/**' + - 'dashscope/**' + - 'mkdocs.yml' + - 'requirements-doc.txt' + - '.github/workflows/docs.yml' + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: pages-${{ github.ref }} + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.12' + # mkdocstrings imports the real package, so install it alongside the + # doc toolchain (httpx/pydantic etc. come in as runtime dependencies). + - run: python -m pip install -r requirements-doc.txt . + - name: Build HTML + run: mkdocs build --strict + - name: Upload site artifact + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + uses: actions/upload-pages-artifact@v3 + with: + path: site + + deploy: + needs: build + if: github.event_name == 'push' && github.ref == 'refs/heads/main' + runs-on: ubuntu-latest + permissions: + pages: write + id-token: write + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.gitignore b/.gitignore index 5b36fd85..e5c0df22 100644 --- a/.gitignore +++ b/.gitignore @@ -67,9 +67,6 @@ instance/ # Scrapy stuff: .scrapy -# Sphinx documentation -docs/_build/ - # PyBuilder .pybuilder/ target/ diff --git a/README.md b/README.md index 6d50ebcf..45fe2c4d 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ > **English** | [中文](README_zh.md) +**Documentation**: [dashscope.github.io/dashscope-sdk-python](https://dashscope.github.io/dashscope-sdk-python/) — [中文文档](https://dashscope.github.io/dashscope-sdk-python/zh/) + The DashScope Python SDK is the official client for [Alibaba Cloud Model Studio (Bailian)](https://www.alibabacloud.com/help/en/model-studio/), covering text generation, multi-modal understanding, embeddings, reranking, image/video generation, speech synthesis & recognition, fine-tuning, agentic RL, applications and more. **Version 2.0** introduces a resource-style client — `dashscope.Client()` — modeled on the ergonomics of the OpenAI SDK: one client holds a shared connection pool, every capability hangs off it as a typed resource (`client.chat`, `client.images`, `client.audio`, …), responses are typed objects instead of raw dicts, and failures raise exceptions by default. The complete 1.x public surface remains available at its historical import paths and is implemented by facades under `dashscope.legacy_1x`; AgentStudio and Agentic RL share their large business cores with 2.0 without sharing public return or error contracts. diff --git a/README_zh.md b/README_zh.md index 3f68189f..9a289566 100644 --- a/README_zh.md +++ b/README_zh.md @@ -2,6 +2,8 @@ > [English](README.md) | **中文** +**文档站点**:[dashscope.github.io/dashscope-sdk-python](https://dashscope.github.io/dashscope-sdk-python/zh/) —— [English docs](https://dashscope.github.io/dashscope-sdk-python/) + DashScope Python SDK 是[阿里云百炼(Model Studio)](https://help.aliyun.com/zh/model-studio/)的官方客户端,覆盖文本生成、多模态理解、向量(Embedding)、重排(Rerank)、图像/视频生成、语音合成与识别、模型调优、Agentic RL、应用调用等能力。 **2.0 版本**引入了资源风格的客户端 —— `dashscope.Client()`,其易用性对标 OpenAI SDK:一个客户端持有共享连接池,每项能力都以类型化资源的形式挂载其上(`client.chat`、`client.images`、`client.audio`……),响应是类型化对象而非裸字典,失败默认抛出异常。1.x 的完整公开接口仍保留在历史导入路径上,由 `dashscope.legacy_1x` 下的 Facade 实现;AgentStudio 与 Agentic RL 与 2.0 共享同一套业务核心,但各自的公开返回类型与错误契约保持独立。 diff --git a/dashscope/legacy_1x/aigc/conversation.py b/dashscope/legacy_1x/aigc/conversation.py index 1f937f3f..3d6ec750 100644 --- a/dashscope/legacy_1x/aigc/conversation.py +++ b/dashscope/legacy_1x/aigc/conversation.py @@ -53,7 +53,7 @@ def add(self, key: str, content: Any): Args: key (str): The key of the content. - value (Any): The history content. + content (Any): The history content. """ self[self.role].append({key: content}) diff --git a/dashscope/legacy_1x/aigc/image_generation.py b/dashscope/legacy_1x/aigc/image_generation.py index 8d896bae..3c6cbda2 100644 --- a/dashscope/legacy_1x/aigc/image_generation.py +++ b/dashscope/legacy_1x/aigc/image_generation.py @@ -56,7 +56,7 @@ def call( # type: ignore[override] [{'role': 'user', 'content': 'The weather is fine today.'}, {'role': 'assistant', 'content': 'Suitable for outings'}] - **kwargs: + **kwargs (Any): stream(bool, `optional`): Enable server-sent events (ref: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) # noqa E501 # pylint: disable=line-too-long the result will back partially[qwen-turbo,bailian-v1]. @@ -374,7 +374,7 @@ async def call( # type: ignore[override] [{'role': 'user', 'content': 'The weather is fine today.'}, {'role': 'assistant', 'content': 'Suitable for outings'}] - **kwargs: + **kwargs (Any): stream(bool, `optional`): Enable server-sent events (ref: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) # noqa E501 # pylint: disable=line-too-long the result will back partially[qwen-turbo,bailian-v1]. diff --git a/dashscope/legacy_1x/aigc/image_synthesis.py b/dashscope/legacy_1x/aigc/image_synthesis.py index fd56c717..c702f94d 100644 --- a/dashscope/legacy_1x/aigc/image_synthesis.py +++ b/dashscope/legacy_1x/aigc/image_synthesis.py @@ -104,7 +104,7 @@ def call( # type: ignore[override] enable_sequential (bool, optional): Enable sequential generation mode. thinking_mode (str, optional): Thinking mode for generation. Supported values: fast, balanced, quality. color_palette (str, optional): Color palette specification for consistent styling. - **kwargs: + **kwargs (Any): similarity(float, `optional`): The similarity between the output image and the input image sketch_weight(int, optional): How much the input sketch @@ -688,7 +688,7 @@ async def call( # type: ignore[override] # pylint: disable=arguments-renamed # enable_sequential (bool, optional): Enable sequential generation mode. thinking_mode (str, optional): Thinking mode for generation. Supported values: fast, balanced, quality. color_palette (str, optional): Color palette specification for consistent styling. - **kwargs: + **kwargs (Any): similarity(float, `optional`): The similarity between the output image and the input image sketch_weight(int, optional): How much the input sketch diff --git a/dashscope/legacy_1x/aigc/video_synthesis.py b/dashscope/legacy_1x/aigc/video_synthesis.py index 12c34384..f7539454 100644 --- a/dashscope/legacy_1x/aigc/video_synthesis.py +++ b/dashscope/legacy_1x/aigc/video_synthesis.py @@ -131,7 +131,7 @@ def call( # type: ignore[override] audio_setting (str, optional): Audio setting for video, "auto" or "origin". enable_thinking (bool, optional): Whether to use Agentic PE. - **kwargs: Additional parameters passed to the API. + **kwargs (Any): Additional parameters passed to the API. Raises: InputRequired: The prompt cannot be empty. @@ -445,7 +445,7 @@ def async_call( # pylint: disable=arguments-renamed # type: ignore[override] # audio_setting (str, optional): Audio setting for video, "auto" or "origin". enable_thinking (bool, optional): Whether to use Agentic PE. - **kwargs: Additional parameters passed to the API. + **kwargs (Any): Additional parameters passed to the API. Raises: InputRequired: The prompt cannot be empty. @@ -708,7 +708,7 @@ async def call( # type: ignore[override] # pylint: disable=arguments-renamed # audio_setting (str, optional): Audio setting for video, "auto" or "origin". enable_thinking (bool, optional): Whether to use Agentic PE. - **kwargs: Additional parameters passed to the API. + **kwargs (Any): Additional parameters passed to the API. Raises: InputRequired: The prompt cannot be empty. @@ -848,7 +848,7 @@ async def async_call( # type: ignore[override] # pylint: disable=arguments-rena shot_type (str, optional): Shot type for video generation. enable_thinking (bool, optional): Whether to use Agentic PE. audio_setting (str, optional): Audio setting for video, - **kwargs: Additional parameters passed to the API. + **kwargs (Any): Additional parameters passed to the API. Raises: InputRequired: The prompt cannot be empty. diff --git a/dashscope/legacy_1x/audio/asr/recognition.py b/dashscope/legacy_1x/audio/asr/recognition.py index 0967f549..3b5c7905 100644 --- a/dashscope/legacy_1x/audio/asr/recognition.py +++ b/dashscope/legacy_1x/audio/asr/recognition.py @@ -171,7 +171,7 @@ class Recognition(BaseApi): sample_rate (int): The input audio sample rate for speech recognition. workspace (str): The dashscope workspace id. - **kwargs: + **kwargs (Any): phrase_id (list, `optional`): The ID of phrase. disfluency_removal_enabled(bool, `optional`): Filter mood words, turned off by default. @@ -385,7 +385,7 @@ def start( Args: phrase_id (str, `optional`): The ID of phrase. - **kwargs: + **kwargs (Any): disfluency_removal_enabled(bool, `optional`): Filter mood words, turned off by default. diarization_enabled (bool, `optional`): @@ -462,7 +462,7 @@ def call( # type: ignore[override] # noqa: E501 file (str): The path to the local audio file. phrase_id (str, `optional`): The ID of phrase. - **kwargs: + **kwargs (Any): disfluency_removal_enabled(bool, `optional`): Filter mood words, turned off by default. diarization_enabled (bool, `optional`): diff --git a/dashscope/legacy_1x/audio/asr/translation_recognizer.py b/dashscope/legacy_1x/audio/asr/translation_recognizer.py index bd32fea9..8dab86f9 100644 --- a/dashscope/legacy_1x/audio/asr/translation_recognizer.py +++ b/dashscope/legacy_1x/audio/asr/translation_recognizer.py @@ -296,7 +296,7 @@ class TranslationRecognizerRealtime(BaseApi): sample_rate (int): The input audio sample rate. workspace (str): The dashscope workspace id. - **kwargs: + **kwargs (Any): phrase_id (list, `optional`): The ID of phrase. disfluency_removal_enabled(bool, `optional`): Filter mood words, turned off by default. @@ -489,9 +489,8 @@ def start( Please call 'stop()' after you have completed translation & recognition. # noqa: E501 Args: - phrase_id (str, `optional`): The ID of phrase. - - **kwargs: + **kwargs (Any): + phrase_id (str, `optional`): The ID of phrase. disfluency_removal_enabled(bool, `optional`): Filter mood words, turned off by default. diarization_enabled (bool, `optional`): @@ -569,7 +568,7 @@ def call( # type: ignore[override] file (str): The path to the local audio file. phrase_id (str, `optional`): The ID of phrase. - **kwargs: + **kwargs (Any): disfluency_removal_enabled(bool, `optional`): Filter mood words, turned off by default. diarization_enabled (bool, `optional`): @@ -815,7 +814,7 @@ class TranslationRecognizerChat(BaseApi): sample_rate (int): The input audio sample rate. workspace (str): The dashscope workspace id. - **kwargs: + **kwargs (Any): phrase_id (list, `optional`): The ID of phrase. disfluency_removal_enabled(bool, `optional`): Filter mood words, turned off by default. @@ -1025,9 +1024,8 @@ def start( Please call 'stop()' after you have completed translation & recognition. # noqa: E501 Args: - phrase_id (str, `optional`): The ID of phrase. - - **kwargs: + **kwargs (Any): + phrase_id (str, `optional`): The ID of phrase. disfluency_removal_enabled(bool, `optional`): Filter mood words, turned off by default. diarization_enabled (bool, `optional`): diff --git a/dashscope/legacy_1x/audio/http_tts/http_speech_synthesizer.py b/dashscope/legacy_1x/audio/http_tts/http_speech_synthesizer.py index ca831955..4a4c262a 100644 --- a/dashscope/legacy_1x/audio/http_tts/http_speech_synthesizer.py +++ b/dashscope/legacy_1x/audio/http_tts/http_speech_synthesizer.py @@ -148,7 +148,7 @@ def call( # type: ignore # pylint: disable=arguments-renamed workspace (str): The DashScope workspace ID. api_key (str): The DashScope API key. url (str): custom http url if needed. - **kwargs: Additional parameters like volume, rate, pitch, etc. + **kwargs (Any): Additional parameters like volume, rate, pitch, etc. Returns: HttpSpeechSynthesisResult: For non-streaming mode. diff --git a/dashscope/legacy_1x/audio/qwen_tts/speech_synthesizer.py b/dashscope/legacy_1x/audio/qwen_tts/speech_synthesizer.py index 423b3598..7864e103 100644 --- a/dashscope/legacy_1x/audio/qwen_tts/speech_synthesizer.py +++ b/dashscope/legacy_1x/audio/qwen_tts/speech_synthesizer.py @@ -45,7 +45,7 @@ def call( # type: ignore[override] if None, will retrieve by rule [1]. [1]: https://help.aliyun.com/zh/dashscope/developer-reference/api-key-settings. # noqa E501 # pylint: disable=line-too-long workspace (str): The dashscope workspace id. - **kwargs: + **kwargs (Any): stream(bool, `optional`): Enable server-sent events (ref: https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) # noqa E501 # pylint: disable=line-too-long the result will back partially[qwen-turbo,bailian-v1]. diff --git a/dashscope/legacy_1x/files.py b/dashscope/legacy_1x/files.py index c3e908c8..8557d382 100644 --- a/dashscope/legacy_1x/files.py +++ b/dashscope/legacy_1x/files.py @@ -79,7 +79,7 @@ def list( # type: ignore[override] Args: api_key (str, optional): - The api api_key, can be None, + The api api_key, can be None, if None, will get by default rule(TODO: api key doc). page (int, optional): Page number. Defaults to 1. page_size (int, optional): Items per page. Defaults to 10. diff --git a/dashscope/legacy_1x/finetune/deployments.py b/dashscope/legacy_1x/finetune/deployments.py index dcf0eff3..38e31e30 100644 --- a/dashscope/legacy_1x/finetune/deployments.py +++ b/dashscope/legacy_1x/finetune/deployments.py @@ -176,7 +176,7 @@ def scale( """Scaling model deployment. Args: - deployment_id (str): The deployment id. + deployed_model (str): The deployed model id. capacity (int): The target service capacity. api_key (str, optional): The api key. Defaults to None. diff --git a/dashscope/legacy_1x/models.py b/dashscope/legacy_1x/models.py index 300a4931..89054bfc 100644 --- a/dashscope/legacy_1x/models.py +++ b/dashscope/legacy_1x/models.py @@ -24,7 +24,8 @@ def get( # type: ignore[override] Args: name (str): The model name. api_key (str, optional): The api key. Defaults to None. - workspace (str): The dashscope workspace id. + **kwargs (Any): + workspace (str): The dashscope workspace id. Returns: DashScopeAPIResponse: The model information. diff --git a/dashscope/legacy_1x/threads/messages/messages.py b/dashscope/legacy_1x/threads/messages/messages.py index 8f2f2f0a..62eab058 100644 --- a/dashscope/legacy_1x/threads/messages/messages.py +++ b/dashscope/legacy_1x/threads/messages/messages.py @@ -267,15 +267,16 @@ def update( # type: ignore[override] Args: thread_id (str): The thread id. message_id (str): The message id. - content (str): The message content. - role (str, optional): The message role. Defaults to 'user'. - file_ids (List[str], optional): - The file_ids include in message. Defaults to []. metadata (Optional[object], optional): The custom key/value pairs. Defaults to None. workspace (str, optional): The DashScope workspace id. Defaults to None. api_key (str, optional): The DashScope api key. Defaults to None. + **kwargs (Any): + content (str): The message content. + role (str, optional): The message role. Defaults to 'user'. + file_ids (List[str], optional): + The file_ids include in message. Defaults to []. Returns: ThreadMessage: The `ThreadMessage` object. diff --git a/dashscope/legacy_1x/threads/runs/runs.py b/dashscope/legacy_1x/threads/runs/runs.py index 904836ad..b67e85eb 100644 --- a/dashscope/legacy_1x/threads/runs/runs.py +++ b/dashscope/legacy_1x/threads/runs/runs.py @@ -582,12 +582,13 @@ def update( # type: ignore[override] Args: thread_id (str): The thread of the run id to be updated. run_id (str): The run id to update. - model (str): The model to use. metadata (Dict, optional): Custom key-value pairs associate with run. Defaults to None. workspace (str): The DashScope workspace id. api_key (str, optional): The DashScope workspace id. Defaults to None. + **kwargs (Any): + model (str): The model to use. Raises: InputRequired: thread id and run is required. diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf1..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/README.md b/docs/README.md index 8ccd292e..d4f66838 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,17 +1,80 @@ -## maintain docs -1. build docs +## Documentation Maintenance Guide + +> **English** | [中文](README_zh.md) + +The documentation is a MkDocs Material project (the same stack as the FastAPI +docs): site configuration lives in `mkdocs.yml` at the repository root, page +sources live in `docs/`, covering the dashscope 2.0 API. The API reference is +generated automatically from source docstrings via mkdocstrings (`::: module.Class` +directives); guides and the quickstart are plain Markdown. + +The site is bilingual: **English is the default language** (`docs/en/`, +published at the site root) and **Simplified Chinese** (`docs/zh/`, published +under `/zh/`), with a language selector in the header (provided by the +`mkdocs-static-i18n` plugin, the same approach FastAPI uses). + +1. Multi-language directory conventions + + ```text + docs/ + ├── en/ # default language (English), mirrors the same subtree + │ ├── index.md / features.md / quickstart.md / cli.md + │ ├── develop.md / about.md / release-notes.md + │ ├── guides/ └ reference/ + ├── zh/ # Chinese translation, one-to-one with en/ + ├── overrides/ # Material template override (per-page action block) + ├── hooks.py # build hook: inject SDK version from dashscope/version.py + └── assets/ + stylesheets/ # logo and custom CSS + ``` + + - New pages: write the English original in `docs/en/` first, then add the + same-named translation in `docs/zh/`; untranslated pages automatically + fall back to the English original. + - Navigation titles are written in English in the `nav` section of + `mkdocs.yml`; Chinese titles are mapped through the i18n plugin's + `nav_translations`. + - The `:::` directives on API reference pages are identical in both + languages (docstrings themselves are English); the zh version + translates headings and introductions, the API body stays English. + - Cross-page auto-references (autorefs) are configured with + `resolve_closest: true`, so references inside Chinese pages point to + Chinese pages and English pages point to English pages. + - `docs/overrides/main.html` overrides the Material template to render + the per-page action block (report issue / contribute); the directory + is excluded from the site via `exclude_docs`. + +2. Local build & preview ```shell - # in root directory: - make docs + # From the repository root: + python -m pip install -r requirements-doc.txt + python -m pip install -e . + mkdocs serve + # Open http://127.0.0.1:8000 in a browser for live preview + # Or build the static site only: + mkdocs build # output in site/ ``` + `site/` is git-ignored and regenerated on every build. + +3. CI publishing -2. doc string format + `.github/workflows/docs.yml` runs `mkdocs build --strict` as a check on + every PR (any warning or broken reference fails the build) + and on pushes to `main` that touch `docs/`, `dashscope/`, `mkdocs.yml` or + `requirements-doc.txt`. Pushes to `main` additionally deploy the HTML to + GitHub Pages (always showing the latest docs, independent of the + tag-driven release workflow). - We adopt the google style docstring format as the standard, please refer to the following documents. - 1. Google Python style guide docstring [link](http://google.github.io/styleguide/pyguide.html#381-docstrings) - 2. Google docstring example [link](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) - 3. sample:torch.nn.modules.conv [link](https://pytorch.org/docs/stable/_modules/torch/nn/modules/conv.html#Conv1d) - 4. load function as an example: + One-time repository setup required: **Settings → Pages → Build and + deployment → Source = "GitHub Actions"**. After the first successful + deployment the site is available at `https://.github.io//`. + +4. Docstring format + + We use Google-style docstrings as the standard. References: + 1. Google Python style guide, docstrings [link](http://google.github.io/styleguide/pyguide.html#381-docstrings) + 2. Google docstring examples [link](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) + 3. Example: torch.nn.modules.conv [link](https://pytorch.org/docs/stable/_modules/torch/nn/modules/conv.html#Conv1d) + 4. Using a load function as an example: ```python def load(file, file_format=None, **kwargs): @@ -34,4 +97,4 @@ Returns: The content from the file. """ - ``` + ``` \ No newline at end of file diff --git a/docs/README_zh.md b/docs/README_zh.md new file mode 100644 index 00000000..dad8113b --- /dev/null +++ b/docs/README_zh.md @@ -0,0 +1,94 @@ +## 文档维护说明 + +> [English](README.md) | **中文** + +文档是一个 MkDocs Material 工程(与 FastAPI 文档同款技术栈): +站点配置在根目录 `mkdocs.yml`,页面源在 `docs/`,覆盖 dashscope 2.0 API。 +API 参考通过 mkdocstrings 从源码 docstring 自动生成(`::: 模块.类名` +指令);专题指南与快速开始为普通 Markdown。 + +站点为双语:**英文为默认语言**(`docs/en/`,发布在站点根路径), +**简体中文**(`docs/zh/`,发布在 `/zh/` 下),顶栏有语言切换器 +(由 `mkdocs-static-i18n` 插件提供,FastAPI 同款方案)。 + +1. 多语言目录约定 + + ```text + docs/ + ├── en/ # 默认语言(英文),镜像同样的子目录结构 + │ ├── index.md / features.md / quickstart.md / cli.md + │ ├── develop.md / about.md / release-notes.md + │ ├── guides/ └ reference/ + ├── zh/ # 中文翻译,与 en/ 一一对应 + ├── overrides/ # Material 模板覆写(每页操作块) + ├── hooks.py # 构建 hook:从 dashscope/version.py 注入版本号 + └── assets/ + stylesheets/ # Logo 与自定义 CSS + ``` + + - 新增页面:先在 `docs/en/` 写英文原版,再在 `docs/zh/` 放同名翻译; + 未翻译的页面会自动回退显示英文原版。 + - 导航标题在 `mkdocs.yml` 的 `nav` 中用英文书写,中文标题通过 + i18n 插件的 `nav_translations` 映射。 + - API 参考页的 `:::` 指令两种语言完全相同(docstring 本身是英文), + zh 版翻译标题与导语,API 正文保持英文。 + - 跨页自动引用(autorefs)已配置 `resolve_closest: true`, + 保证中文页内的引用指向中文页、英文页指向英文页。 + - `docs/overrides/main.html` 覆写 Material 模板,在每页底部渲染 + 页面操作块(报告问题 / 贡献);该目录经 `exclude_docs` 排除, + 不进入站点。 + +2. 本地构建与预览 + ```shell + # 在仓库根目录: + python -m pip install -r requirements-doc.txt + python -m pip install -e . + mkdocs serve + # 浏览器打开 http://127.0.0.1:8000 实时预览 + # 或仅构建静态站点: + mkdocs build # 产物在 site/ + ``` + `site/` 已被 git 忽略,每次构建都会重新生成。 + +3. CI 自动发布 + + `.github/workflows/docs.yml` 会在每个 PR 以及推送到 `main` 且 + 改动涉及 `docs/`、`dashscope/`、`mkdocs.yml` 或 + `requirements-doc.txt` 时执行 `mkdocs build --strict` 校验 + (任何警告或坏引用都会使构建失败)。 + 推送到 `main` 还会把 HTML 部署到 GitHub Pages(始终展示最新文档, + 与基于 tag 的发布流程相互独立)。 + + 仓库需要一次性设置:**Settings → Pages → Build and deployment → + Source = "GitHub Actions"**。首次部署成功后,站点地址为 + `https://.github.io//`。 + +4. docstring 格式 + + 我们采用 Google 风格的 docstring 作为标准,参考以下资料: + 1. Google Python 风格指南 docstring [链接](http://google.github.io/styleguide/pyguide.html#381-docstrings) + 2. Google docstring 示例 [链接](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) + 3. 范例:torch.nn.modules.conv [链接](https://pytorch.org/docs/stable/_modules/torch/nn/modules/conv.html#Conv1d) + 4. 以 load 函数为例: + + ```python + def load(file, file_format=None, **kwargs): + """Load data from json/yaml/pickle files. + + This method provides a unified api for loading data from serialized files. + + Args: + file (str or :obj:`Path` or file-like object): Filename or a file-like + object. + file_format (str, optional): If not specified, the file format will be + inferred from the file extension, otherwise use the specified one. + Currently supported formats include "json", "yaml/yml". + + Examples: + >>> load('/path/of/your/file') # file is stored in disk + >>> load('https://path/of/your/file') # file is stored on internet + >>> load('oss://path/of/your/file') # file is stored in petrel + + Returns: + The content from the file. + """ + ``` \ No newline at end of file diff --git a/docs/assets/logo.svg b/docs/assets/logo.svg new file mode 100644 index 00000000..3f0a15c3 --- /dev/null +++ b/docs/assets/logo.svg @@ -0,0 +1,4 @@ + + + + \ No newline at end of file diff --git a/docs/en/about.md b/docs/en/about.md new file mode 100644 index 00000000..97845b8c --- /dev/null +++ b/docs/en/about.md @@ -0,0 +1,47 @@ +--- +description: "About the DashScope Python SDK: project links, Apache-2.0 license, compatibility and versioning policy." +--- +# About + +## The project + +The DashScope Python SDK (`dashscope` on PyPI) is the official Python client +for [Alibaba Cloud Model Studio (Bailian)](https://www.alibabacloud.com/help/en/model-studio/), +covering text generation, multimodal understanding, embeddings, reranking, +image/video generation, speech synthesis & recognition, fine-tuning, +agentic RL, managed agents and applications. + +- Source code: [github.com/dashscope/dashscope-sdk-python](https://github.com/dashscope/dashscope-sdk-python) +- Package: [pypi.org/project/dashscope](https://pypi.org/project/dashscope/) +- Service documentation: [Model Studio help center](https://www.alibabacloud.com/help/en/model-studio/) + +## License + +The SDK is licensed under the +[Apache License 2.0](https://github.com/dashscope/dashscope-sdk-python/blob/main/LICENSE). +Third-party notices (e.g. the bundled certifi CA bundle) are listed in +[NOTICE](https://github.com/dashscope/dashscope-sdk-python/blob/main/NOTICE). + +## Compatibility and versioning + +- The 2.x line is the actively developed API: resource-style `Client` / + `AsyncClient`, typed responses and exceptions. +- The complete 1.x public surface remains importable from its historical + paths and is implemented by frozen facades under `dashscope.legacy_1x`; + it receives no new features. +- AgentStudio and Agentic RL are application sub-SDKs with their own client, + return and error contracts. +- Python 3.9+ is required; the optional interactive assistant + (`dashscope[acli]`) requires Python 3.10+. +- Current SDK version: **{{ sdk_version }}** — see + [Release Notes](release-notes.md). + +## Getting help + +- Report bugs and request features in + [GitHub Issues](https://github.com/dashscope/dashscope-sdk-python/issues). +- Browse the [API Reference](reference/client.md) or the + [Quickstart](quickstart.md). +- Failed calls can explain themselves: enable the devkit diagnosis to get + structured fix guidance on `DashScopeError.diagnosis` + (see [Devkit](reference/devkit.md)). \ No newline at end of file diff --git a/docs/en/cli.md b/docs/en/cli.md new file mode 100644 index 00000000..e996f32f --- /dev/null +++ b/docs/en/cli.md @@ -0,0 +1,79 @@ +--- +description: "The dashscope command line: global options, exit codes and every command group." +--- +# Command Line Interface + +Installing the SDK also installs the `dashscope` command (and `dashscope1` +for the archived 1.x command tree). The CLI mirrors the SDK resources, so +anything you can do with `Client` you can also script from a shell. + +```bash +dashscope version # print the SDK version (a subcommand, not --version) +dashscope auth login # save an API key (prompted interactively) +dashscope chat create --model qwen-plus --prompt "Hello!" +dashscope -k sk-xxx --output json ft list +``` + +## Global options + +Global options come **before** the subcommand: + +| Option | Meaning | +| --- | --- | +| `-k`, `--api-key` | DashScope API key; overrides environment and config file. | +| `--protocol` | Wire protocol: `native`, `openai` or `anthropic`. | +| `--base-url` | Override the service base URL. | +| `--workspace` | Workspace (business space) ID. | +| `--region` | Service region, e.g. `cn-beijing`, `ap-southeast-1`. | +| `--timeout` | Per-request timeout in seconds. | +| `-o`, `--output` | Output format; machine formats keep stdout parseable (e.g. `json`). | + +Errors go to stderr as `Error [category]: message`. Exit codes: `0` ok, +`1` server / rate-limit / network, `2` bad command line, `3` auth, +`4` not found. + +## Command groups + +| Group | Purpose | +| --- | --- | +| `auth` | `login` / `whoami` / `logout` — manage the stored API key. | +| `config` | `set` / `get` / `list` — persistent CLI configuration. | +| `chat` | Chat completions (sync and streaming). | +| `multimodal` | Multimodal understanding / generation calls. | +| `embeddings` | Text embedding calls and batch jobs. | +| `rerank` | Document reranking. | +| `tokenization` | Token counting. | +| `images` | Image generation jobs. | +| `videos` | Video generation jobs. | +| `audio` | TTS / ASR / realtime audio commands. | +| `files` | Upload, list, get and delete files. | +| `models` | Browse the model catalog. | +| `ft` | Fine-tuning jobs (`fine-tunes` is a hidden alias). | +| `deployments` | Manage model deployments. | +| `rl` | Agentic RL datasets, functions and jobs (`agentic-rl` alias). | +| `apps` | Model Studio application completions. | +| `tingwu` | Meeting transcription and analysis. | +| `decision` | Structured decision / judging calls. | +| `agentstudio` | AgentStudio managed-agent resources. | +| `oss` | OSS upload helpers for large media inputs. | + +Run `dashscope --help` (or `dashscope --help`) for +the exact arguments of each command. + +## The agent entry point + +Invoking `dashscope` with **no arguments** starts the interactive AgenticX +agent instead of the command tree. It requires the optional extra and +Python 3.10+: + +```bash +pip install -U "dashscope[acli]" +dashscope # launches the agent +``` + +## The 1.x CLI + +The legacy command tree (`generation create`, `application create`, +`files.upload`, `login`, ...) is installed separately as `dashscope1` and is +frozen. Running a 1.x command name under `dashscope` only prints a migration +hint pointing at `dashscope1` or the 2.0 equivalent. \ No newline at end of file diff --git a/docs/en/develop.md b/docs/en/develop.md new file mode 100644 index 00000000..28e7c0e6 --- /dev/null +++ b/docs/en/develop.md @@ -0,0 +1,51 @@ +--- +description: "Developer guide: repository layout, tests, docstring conventions and release process." +--- +# Develop + +## 1. Code Style +We adopt [PEP8](https://www.python.org/dev/peps/pep-0008/) as the preferred code style. + +We use the following tools for linting and formatting: +- [flake8](http://flake8.pycqa.org/en/latest/): linter +- [yapf](https://github.com/google/yapf): formatter +- [isort](https://github.com/timothycrosley/isort): sort imports + +Style configurations of yapf and isort can be found in [setup.cfg](https://github.com/dashscope/dashscope-sdk-python/blob/main/setup.cfg). +We use a [pre-commit hook](https://pre-commit.com/) that checks and formats for `flake8`, `yapf`, `seed-isort-config`, `isort`, `trailing whitespaces`, +fixes `end-of-files`, and sorts `requirements.txt` automatically on every commit. +The config for the pre-commit hook is stored in [.pre-commit-config](https://github.com/dashscope/dashscope-sdk-python/blob/main/.pre-commit-config.yaml). +After you clone the repository, you will need to install and initialize the pre-commit hook: +```bash +pip install -r requirements-test.txt +``` +From the repository folder: +```bash +pre-commit install +``` + +After this, code linters and formatters will be enforced on every commit. + +If you want to use pre-commit to check all the files, you can run: +```bash +pre-commit run --all-files +``` + +If you only want to format and lint your code, you can run: +```bash +make linter +``` + +## 2. Tests + +Run the current root implementation, archived compatibility suites, or the +complete suite with: + +```bash +python -m pytest tests --ignore=tests/legacy_1x -q +python -m pytest tests/legacy_1x -q +python -m pytest tests -q +``` + +Current coverage uses `coverage run -m pytest tests +--ignore=tests/legacy_1x`, followed by `coverage report -m`. \ No newline at end of file diff --git a/docs/en/features.md b/docs/en/features.md new file mode 100644 index 00000000..9ac81dca --- /dev/null +++ b/docs/en/features.md @@ -0,0 +1,96 @@ +--- +description: "Feature overview of the dashscope 2.0 SDK: typed resources, sync/async, protocols, streaming, errors, dev mock, CLI and 1.x compatibility." +--- +# Features + +The dashscope 2.0 SDK is a typed, resource-style client for Alibaba Cloud +Model Studio (DashScope). Highlights: + +## Typed resource client + +- One `Client()` holds a keep-alive connection pool shared by every resource. +- Capabilities hang off the client as typed namespaces: `client.chat`, + `client.images`, `client.audio`, `client.files`, `client.fine_tunes`, … +- Responses are typed objects: read `resp.output_text` and + `resp.usage.total_tokens` instead of digging through raw dicts. +- Failures raise typed exceptions by default — no manual `status_code` checks. + +See [Client & Configuration](reference/client.md). + +## Sync and async, one surface + +- `dashscope.AsyncClient()` mirrors the sync client method-for-method. +- Shared configuration layering: arguments → `dashscope.settings` → + environment variables → `~/.dashscope/config.toml`. +- Exception: the duplex audio WebSocket sessions are sync-only. + +## One client, three protocols + +- The same `client.chat.completions` call speaks DashScope `native`, + OpenAI-compatible or Anthropic-compatible wire protocols. +- Select with `Client(protocol="openai")`, the `protocol` setting or + `DASHSCOPE_PROTOCOL`. + +See [Protocols](reference/protocols.md). + +## Streaming that reads like text + +- `ChatStream` exposes `.text_stream`, `.reasoning_stream` and + `.get_final_message()` — iterate plain strings, get the assembled + typed message at the end. +- SSE transport with automatic retry and reconnect handling. + +See [Chat](reference/chat.md). + +## Realtime voice over WebSocket + +- Speech synthesis (TTS), recognition (ASR), omni realtime and Qwen Live + sessions under `client.audio`. +- Voice and vocabulary customization resources. + +See [Audio](reference/audio.md) and the +[Qwen Live guide](guides/qwen-live-python-sdk.md). + +## Typed errors and self-diagnosis + +- A `DashScopeError` hierarchy covering transport, validation, HTTP status + and WebSocket failures, with `code`, `request_id` and response body attached. +- Opt-in local diagnosis turns a failure into structured, bilingual fix + guidance on `error.diagnosis`. + +See [Errors](reference/errors.md) and [Devkit](reference/devkit.md). + +## Offline development with dev mock + +- `static` / `replay` / `record` modes exercise the full HTTP request path + without spending cloud tokens. +- Zero overhead when disabled; nothing is imported on the success path. + +See [Devkit](reference/devkit.md). + +## Managed agents and agentic RL + +- `dashscope.applications.agentstudio`: a self-contained sub-SDK for managed + agents, sessions, environments, deployments, memory, skills and vaults. +- `dashscope.applications.finetune.AgenticRL` plus decorators to author + rollout / reward functions locally. + +See [AgentStudio](reference/agentstudio.md) and +[Agentic RL](reference/agentic-rl.md). + +## A real command line + +- The `dashscope` CLI covers chat, audio, images, files, fine-tunes, + deployments, RL, apps and more with consistent global options and + machine-readable output (`-o json`). +- Optional interactive AI assistant via `pip install "dashscope[acli]"`. + +See [CLI](cli.md). + +## 1.x compatibility, frozen + +- The complete 1.x public surface still imports from its historical paths + (`from dashscope import Generation`), implemented by frozen facades under + `dashscope.legacy_1x`. + +See [Legacy 1.x](reference/legacy.md). \ No newline at end of file diff --git a/docs/en/guides/qwen-live-python-sdk.md b/docs/en/guides/qwen-live-python-sdk.md new file mode 100644 index 00000000..0651465a --- /dev/null +++ b/docs/en/guides/qwen-live-python-sdk.md @@ -0,0 +1,532 @@ +--- +description: "Full walkthrough of Qwen Live realtime voice sessions over WebSocket with the dashscope SDK." +--- +# Qwen Live Python SDK + +Qwen Live is a WebSocket model for realtime voice interaction: the client +streams audio upstream continuously, and the server returns audio, transcripts +and usage events. The interface lives at `client.audio.live` and provides +connection management, session configuration, audio upstream, delegation +write-back and event iteration. + +This guide shows how to use the Python SDK with Qwen Live to complete the +minimal loop of "send audio → receive and save the reply", plus text input and +delegation modes. Qwen Live uses the `session.*` event family, which is a +different protocol from Omni / Qwen-Audio's `input_audio_buffer.*` and +`response.*`. + +--- + +## Prerequisites + +- **Install the SDK**: Python 3.9 or newer is required, with a DashScope 2.1 + SDK that includes `client.audio.live`. This guide uses the `dashscope` and + `dashscope.resources.audio` import paths, not `dashscope.v2`. + + ```bash + python -m pip install -U "dashscope>=2.1.0" + python -c "from dashscope import Client; from dashscope.resources.audio import LiveSession" + ``` + + If `LiveSession` still cannot be imported after upgrading, use the + Live-capable SDK version specified by your service provider. + +- **Configure the API key**: the `DASHSCOPE_API_KEY` environment variable is + recommended; never hard-code keys. The Client resolves configuration in the + order `explicit arguments → process-level settings → environment variables → + config.toml → key file`; the key must have access to the target environment. + + ```bash + export DASHSCOPE_API_KEY="" + export DASHSCOPE_WORKSPACE="" + ``` + +- **Confirm the endpoint and models**: Qwen Live uses a workspace-dedicated + gateway. The default URL template is + + ``` + wss://{workspace}.{region}.maas.aliyuncs.com/api-ws/v1/realtime + ``` + + `region` defaults to `cn-beijing`; `ap-southeast-1`, `cn-hongkong`, + `us-east-1`, `eu-central-1` and `ap-northeast-1` are also supported. Without + a workspace the SDK falls back to the region's shared gateway + (`wss://dashscope.aliyuncs.com` for Beijing) and prints a `UserWarning`. + + > **Important**: the SDK automatically appends `?model=` to the + > URL; if `ws_url` already carries a `model` query parameter, the existing + > value wins. For private or pre-release deployments, pass the full address + > explicitly via `ws_url`. The route model name (`connect`) and the session + > model name (`update_session`) depend on what your environment actually + > provides. + +--- + +## Request parameters + +Parameters come in three layers: **connection parameters** decide where to +connect and how to authenticate; **session configuration** is sent as the +`session.update` payload and decides session behavior; **delegation +configuration** decides who produces the reply. The route model, frontend +model and backend model belong to these three layers respectively — do not +reuse one name across them. + +### 1. Connection parameters `client.audio.live.connect(...)` + +Returns a `LiveSession` that is not yet connected; the handshake happens only +when you call `connect()` or enter the `with` context. + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `model` | `str` | Yes | Gateway route model name, written into the URL's `?model=`. | +| `ws_url` | `str` | No | Explicit full address; takes precedence over the template. | +| `timeout` | `float` | No | Handshake and per-socket send/receive timeout (seconds); must be positive. Defaults to the Client config when omitted; it is not a cap on the whole session duration. | +| `headers` | `Mapping[str, str]` | No | Custom handshake headers; passed values win on name conflicts. | +| `api_key` | `str` | No | Key for this connection, sent as `Authorization: Bearer`; when omitted or empty, the Client's resolved key is used. | +| `workspace` | `str` | No | Workspace ID; defaults to the Client config. Affects the default URL and the `X-DashScope-WorkSpace` header; an explicit `ws_url` is never rewritten. | +| `connector` | `Callable` | No | Custom connection factory, for tests or special transports only. | + +```python +import os +from dashscope import Client + +with Client(region="cn-beijing") as client: + session = client.audio.live.connect( + model=os.getenv("LIVE_ROUTE_MODEL", "qwen-live"), + ws_url=os.getenv("LIVE_WS_URL"), + timeout=30, + ) # Not yet handshaken; see the full example below +``` + +### 2. Session configuration `update_session(...)` + +Serialized into the `session` node of `session.update`; only explicitly passed +fields are sent. After the server validates, prepares and commits the config +it returns `session.updated` (first success has `revision=1`); on failure no +new config is committed and only an `error` is returned. + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `model` | `str` | Yes | Session (frontend) model name, e.g. `audio-live`, `qwen-audio-realtime`; available names depend on the deployment — the SDK has no model whitelist. | +| `delegation` | `Dict` | Yes | Delegation configuration, see below. | +| `instructions` | `str` | No | System prompt for the frontend model. | +| `voice` | `str` | No | Voice; enum `台湾女声`, `星悦`, `古风女声`, `古风男声`; the deployment default is used when omitted. | +| `tts` | `Dict` | No | Voice configuration for Audio Live; only `system_prompt` is supported. | +| `input_audio_format` | `str` | No | Upstream audio format; only `pcm` is accepted. | +| `output_audio_format` | `str` | No | Downstream audio format; only `pcm` is accepted. | +| `modalities` | `List[str]` | No | Output modalities, default `["text", "audio"]`. | +| `tools` | `List[Dict]` | No | Frontend function tools, default empty array. | +| `context` | `Dict` | No | Context node; actually required by the server, see the note below. | +| `turn_detection` | `Dict` or `None` | No | Turn-detection config; omitting differs from explicit `None` (the latter sends JSON `null`); available options depend on the frontend model. | +| `input_audio_transcription` | `Dict` or `None` | No | Input transcription config; explicit `None` is sent as JSON `null` verbatim. | +| `transport` | `Dict` | No | Omitted or empty object means the default WebSocket; the only explicit transport implemented is `aoq`. | +| `parameters` | `Dict` | No | Pass-through container for new server-side fields, merged key-by-key into the `session` node; cannot override the named fields above. | +| `event_id` | `str` | No | Client event ID for this request, 1–128 characters; generated by the SDK when omitted. Other send methods support it too. | + +> **Note**: the server requires `context.compaction` to be configured, +> otherwise it returns `invalid_session_configuration` with the message +> `session.update: context_compaction_not_configured`. Even when compaction is +> disabled it must be sent explicitly: +> `{"compaction": {"enabled": False, "mode": "local"}}`. When setting +> `tts.system_prompt` for `audio-live` explicitly, it must start with the exact +> sentence `You are a helpful assistant and asked to generate both text and +> speech tokens at the same time.`; if you do not customize it, omit `tts` — +> the SDK does not add the prefix for you. + +Invalid delegation types, an empty backend model, non-`pcm` audio formats and +similar cases raise `ValueError` locally in the SDK without any network +request. + +```python +session.update_session( + model="audio-live", + instructions="Answer the user's voice questions concisely", + input_audio_format="pcm", + output_audio_format="pcm", + context={"compaction": {"enabled": False, "mode": "local"}}, + delegation={"type": "none"}, +) +``` + +### 3. Delegation configuration `delegation` + +Decides "who produces the reply". + +| Parameter | Type | Required | Description | +| --- | --- | --- | --- | +| `type` | `str` | Yes | `none` (no delegation), `client` (external agent), `responses` (backend model). | +| `responses` | `Dict` | Required in `responses` mode | Backend model configuration; must not be present in other modes. | +| `responses.model` | `str` | Yes | Backend model name; must match the current deployment — use what your environment provides. | +| `responses.instructions` | `str` | No | Backend model prompt. | +| `responses.tools` | `List[Dict]` | No | Tools available to the backend model. | + +- **`none`**: the frontend model produces replies itself; the client only + streams audio upstream. +- **`client`**: the server produces no reply; instead it emits + `session.delegation.created`, and your external agent writes content back + via `append_instruction` / `append_thinking` / `append_commentary`, which the + frontend model then renders as speech. +- **`responses`**: the backend model produces replies directly; the client + only streams audio upstream (optionally use `create_response_item` / + `create_response` to add input or request a reply proactively). + +See example 2 for configuration; the SDK only sends and receives events — it +never runs external agents or tools automatically. + +--- + +## Key interface `LiveSession` + +A single instance can hold only one open connection at a time; after close +completes you may explicitly `connect()` again — the SDK clears local session +state but does not restore the old session or replay audio. All send methods +return **the `event_id` of this request**, not a server acknowledgment. + +| Method / property | Server event triggered | Description | +| --- | --- | --- | +| `connect()` | `session.created` | Opens the WebSocket; `with` opens and releases it automatically. Only means the connection is open — **not that the session is configured**. | +| `update_session(...)` | `session.updated` | Sends the session configuration. | +| `append_audio(audio, *, event_id=None)` | — | Appends an audio frame; accepts `bytes` or Base64 `str`; empty data or an odd byte count raises `ValueError`. | +| `mute_input_audio()` / `unmute_input_audio()` | `session.input_audio.muted` / `.unmuted` | Mutes / unmutes upstream; audio from the muted period is not replayed after unmuting. | +| `append_commentary(content, *, delegation_id=None, ...)` | `session.commentary.appended` | Without `delegation_id`, sends user text; with `delegation_id`, writes back the task result of a `client` delegation. | +| `append_instruction(content, *, delegation_id, ...)` | `session.instructions.appended` | Writes a prompt back to the given delegation (`client` mode). | +| `append_thinking(content, *, delegation_id, ...)` | `session.thinking.appended` | Writes back silent reasoning context; speech output is not guaranteed. | +| `create_session_item(item=omitted)` | — | Sends `session.item.create`; omitting `item` omits the field, which differs from passing `None` explicitly. | +| `submit_function_output(call_id, output)` | — | Answers a frontend function call inside `session.event`; not for backend tools. | +| `create_response_item(item)` | — | Appends an input item to the Responses backend; does not trigger a reply. | +| `create_response(response=None)` | Depends on mode | Starts a backend task in `responses` mode; requests an answer from frontends that support proactive replies. See example 2 for plain-text usage. | +| `end_session()` | `session.closed` | Sends the business event `session.close`; no further input is allowed afterwards — keep receiving until `session.closed`. Repeated calls while the close request is pending return the same request ID. | +| `close()` | — | Waits up to 1 second for in-flight sends, then sends a standard WebSocket Close (1000) and independently waits up to 1 second for the handshake; either stage timing out forces release, with no guarantee the peer received the Close frame. Does not wait for the business event `session.closed`; repeated calls are safe. | +| `cancel()` | — | Immediately aborts and releases the socket without a close handshake. Corresponds to the Java SDK's `cancel()`. | +| `send_event(event)` | Depends on payload | Low-level entry point for sending any protocol event; `type` must be a non-blank string, `event_id` is auto-generated when omitted. | +| `model` / `url` | — | Route model name / actual handshake URL (including `?model=`). | +| `session_id` / `close_reason` | — | `session.id` from `session.created` / `reason` from `session.closed`; `None` until received. | +| `last_message` | — | The most recent server event. | + +> **Audio requirements**: upstream is 16 kHz, mono, 16-bit signed +> little-endian raw PCM (PCM16LE); downstream is 24 kHz, mono, PCM16LE, Base64 +> encoded, with no WAV / container header. The SDK does not resample, does not +> recognize WAV containers and does not change byte order — strip WAV headers +> first. Wait for `session.updated` before streaming: 3200 bytes per frame +> (100 ms), wait 100 ms after each `append_audio()` returns; after the delay +> **do not catch up by bursting and do not drop input frames** — the actual +> send rate is slightly below 1x. Pacing is the application's responsibility; +> the SDK does not rate-limit. After the file ends, keep sending silence +> frames to maintain `audio-live`'s duplex audio clock until the application +> decides to end the session. + +--- + +## Event iteration & error contract + +Consume events on one receiving thread while audio goes upstream on another; +the main thread can also receive, as in the full example. The SDK locks the +send and receive directions separately and never creates background threads +automatically. Do not consume the same connection with both `events()` and +`recv_event()`. + +| Method | Description | +| --- | --- | +| `events()` | Iterator that keeps yielding events until a normal close. Recoverable `error` events are yielded without raising; fatal errors raise. | +| `recv_event()` | Reads one event; server errors always raise, only recoverable errors keep the connection. Returns `None` after a normal close. | + +> **Error contract**: `error.type == "invalid_request_error"` is a recoverable +> business error; other business errors close the connection. Unexpected +> disconnects, timeouts and invalid events raise `APIConnectionError`, +> `APITimeoutError` and `WsEventError` respectively; handshake HTTP errors map +> to the corresponding exceptions (401 → `AuthenticationError`, 429 → +> `RateLimitError`). All of these inherit `DashScopeError`; WebSocket business +> errors have `status_code == None`. Fatal failures are remembered — later +> receives keep raising the same exception, and `close()` does not clear the +> failure; after a local close / cancel with no recorded failure, receives +> return `None`. `KeyboardInterrupt` and `SystemExit` propagate unchanged. + +```python +from dashscope import DashScopeError + +try: + for event in session.events(): + if event["type"] == "error": + print(event["error"]) # Recoverable; decide whether to continue +except DashScopeError as exc: + print(f"[error] {exc}") +``` + +### Server event types + +Distinguish them by the `type` field in the event loop. Event-name constants +are importable from `dashscope.resources.audio` or +`dashscope.resources.audio.live`, e.g. `EVENT_SESSION_UPDATED`, +`EVENT_SESSION_OUTPUT_AUDIO_DELTA`, matching the literals in the table below: + +| Event `type` | Meaning | +| --- | --- | +| `session.created` | Session created, with `session.id` and server defaults; one connection may receive several (one from the routing layer, one from the frontend). | +| `session.updated` | Session configuration took effect (**wait for this event before streaming audio**), with the full config and `revision`. | +| `session.input_transcript.delta` | Transcript chunk of the user's upstream speech; timestamps follow the server's actual output. | +| `session.output_transcript.delta` | Assistant reply text chunk. | +| `session.output_audio.delta` | Downstream audio chunk; `delta` is Base64 raw PCM16LE. | +| `session.output_audio.interrupted` | The current downstream audio was interrupted — **not** an end-of-reply signal. | +| `session.commentary.appended` / `session.instructions.appended` / `session.thinking.appended` | Acknowledgments of delegation write-back content. | +| `session.input_audio.muted` / `session.input_audio.unmuted` | Mute-state acknowledgments. | +| `session.delegation.created` | The frontend dispatches a new task or supplement, with `delegation_id`, `offset_ms`, `summary`, `context`; sent in both `client` and `responses` modes. | +| `session.event` | Nested events from the frontend model; function calls inside can be answered with `submit_function_output`. | +| `response.event` | Native events of the backend Responses model; observe backend token usage here. | +| `session.usage.updated` | Usage updates, e.g. cumulative audio duration `usage.seconds`; reporting cadence and fields follow the server. | +| `session.closed` | Session closed, with `reason` (`close_requested` / `expired` / `content` / `remote_hangup` / `connection_lost`) and final `usage`. | +| `error` | Server error, with `error.type` (`invalid_request_error` / `server_error`), `error.code`, `error.message`. | + +The protocol may add new event types; ignore unknown `type` values instead of +raising. + +--- + +## Full examples + +### Example 1: minimal loop (voice file input) + +Save as `qwen_live_quickstart.py`. Streams one PCM / WAV file upstream, prints +transcripts in both directions and saves the reply. After the file ends, the +sender thread keeps streaming silence and independently checks whether the +reply has gone quiet; the main thread keeps receiving until `session.closed`. +This example does not capture a microphone or play audio automatically. + +```python +import base64 +import os +import sys +import time +import wave +from array import array +from concurrent.futures import ThreadPoolExecutor +from pathlib import Path +from threading import Event, Lock + +from dashscope import Client + +FRONTEND_MODEL = os.getenv("LIVE_FRONTEND_MODEL", "audio-live") +FRAME_BYTES = 3200 +IDLE_SECONDS = 5.0 +REPLY_TIMEOUT = 90.0 +CLOSE_TIMEOUT = 5.0 + + +def read_pcm(path): + path = Path(path) + if path.suffix.lower() == ".pcm": + pcm = path.read_bytes() + elif path.suffix.lower() == ".wav": + with wave.open(str(path), "rb") as audio: + if (audio.getnchannels(), audio.getsampwidth(), audio.getframerate(), + audio.getcomptype()) != (1, 2, 16000, "NONE"): + raise ValueError("WAV must be 16 kHz, mono, 16-bit PCM") + pcm = audio.readframes(audio.getnframes()) + if len(pcm) != audio.getnframes() * 2: + raise ValueError("WAV data is truncated") + else: + raise ValueError("Only .pcm or .wav files are supported") + if not pcm or len(pcm) % 2: + raise ValueError("Audio must be non-empty, even-byte PCM16LE") + return pcm + + +def send_audio(session, pcm, stopped, progress, lock): + try: + for offset in range(0, len(pcm), FRAME_BYTES): + if stopped.is_set(): + return + session.append_audio(pcm[offset:offset + FRAME_BYTES].ljust(FRAME_BYTES, b"\0")) + if stopped.wait(0.1): + return + input_finished = time.monotonic() + while not stopped.is_set(): + now = time.monotonic() + with lock: + text_at, audio_at = progress["text"], progress["audio"] + if text_at is not None and audio_at is not None: + if now - max(input_finished, text_at, audio_at) >= IDLE_SECONDS: + with lock: + progress["closing"] = True + session.end_session() # Stop sending audio; main thread waits for the close ack + if not stopped.wait(CLOSE_TIMEOUT): + raise TimeoutError("session.closed not received") + return + if now - input_finished >= REPLY_TIMEOUT: + raise TimeoutError("Reply did not finish within the wait window") + session.append_audio(bytes(FRAME_BYTES)) + stopped.wait(0.1) + except Exception: + session.cancel() # Wake the receiver on send failure; the exception surfaces via sender.result() + raise + + +def main(input_path, output_path): + pcm = read_pcm(input_path) + stopped, lock = Event(), Lock() + progress = {"text": None, "audio": None, "closing": False} + with Client() as client: + with client.audio.live.connect( + model=os.getenv("LIVE_ROUTE_MODEL", "qwen-live"), + ws_url=os.getenv("LIVE_WS_URL"), timeout=30, + ) as session: + with ThreadPoolExecutor(max_workers=1) as pool, open(output_path, "xb") as out: + sender = None + try: + session.update_session( + model=FRONTEND_MODEL, delegation={"type": "none"}, + instructions="Answer the user's voice questions concisely", + input_audio_format="pcm", output_audio_format="pcm", + context={"compaction": {"enabled": False, "mode": "local"}}, + ) + for event in session.events(): + kind = event["type"] + if kind == "session.updated" and sender is None: + sender = pool.submit(send_audio, session, pcm, stopped, progress, lock) + elif kind == "session.input_transcript.delta": + print(f"\n[user] {event['delta']}", flush=True) + elif kind == "session.output_transcript.delta": + if event["delta"]: + with lock: + progress["text"] = time.monotonic() + print(event["delta"], end="", flush=True) + elif kind == "session.output_audio.delta": + data = base64.b64decode(event["delta"], validate=True) + if not data or len(data) % 2: + raise ValueError("Downstream audio is not valid PCM16LE") + out.write(data) + samples = array("h", data) + if sys.byteorder != "little": + samples.byteswap() + if sum(x * x for x in samples) >= len(samples) * 150 ** 2: + with lock: + progress["audio"] = time.monotonic() + elif kind == "error": + raise RuntimeError(event["error"]) # This example exits on any error + elif kind == "session.closed": + with lock: + requested = progress["closing"] + if not requested or event.get("reason") != "close_requested": + raise RuntimeError(f"Session ended early: {event.get('reason')}") + print(f"\nClose reason: {event.get('reason')}") + break + finally: + stopped.set() + session.close() # Bounded WebSocket close first, then wait for the sender thread + if sender is not None: + sender.result() + print() + + +if __name__ == "__main__": + try: + main(sys.argv[1], sys.argv[2]) + except KeyboardInterrupt: + print() +``` + +Configure a workspace, or pass the endpoint explicitly via `LIVE_WS_URL`; +`LIVE_ROUTE_MODEL` sets the route model and `LIVE_FRONTEND_MODEL` the frontend +model. These three `LIVE_*` variables are read by the example — they are not +SDK global settings. `output.pcm` must not exist when running: + +```bash +python qwen_live_quickstart.py input.pcm output.pcm +``` + +`output.pcm` is 24 kHz, mono, 16-bit raw PCM, including received silence +frames. The example treats RMS ≥ 150 as audible output; after receiving text +and audible audio, it waits until the input has ended and both have been quiet +for 5 consecutive seconds before requesting close. This is not a server-side +completion confirmation — long pauses or background noise can affect the +judgment. After the input ends it waits up to 90 seconds for the reply, and up +to 5 more seconds after sending the close request; timeouts cancel the +connection and raise. Receiving a close event before the completion conditions +are met also raises. + +### Example 2: text input & delegation modes + +**Plain text input**: on frontends that support proactive text replies, +`append_commentary()` must be followed by `create_response()`; the former's +acknowledgment does not mean answering has started. In example 1's `main()`, +change `pcm = read_pcm(input_path)` to `pcm = b""`, and replace the +`pool.submit(...)` line in the `session.updated` branch with the code below; +everything else stays the same. Empty input only sends silence to maintain the +audio clock: + +```python +session.append_commentary("Hello, please introduce yourself in one sentence.") +session.create_response() +sender = pool.submit(send_audio, session, pcm, stopped, progress, lock) +``` + +**Backend model delegation**: keep example 1's voice input, define the +following variables before configuration, and replace +`delegation={"type": "none"}` in `update_session()` with +`delegation=delegation`. `create_response_item()` is only for backend input in +this mode — it cannot replace `append_commentary()` in `none` mode: + +```python +delegation = { + "type": "responses", + "responses": { + "model": "", + "instructions": "Answer the user directly without external tools", + }, +} +``` + +**External agent delegation**: change example 1's configuration to +`delegation={"type": "client"}` and add the branch below to the event loop. +Fixed text is used here to demonstrate write-back; real results come from your +agent: + +```python +elif kind == "session.delegation.created": + session.append_commentary("Cloudy turning sunny in Hangzhou tomorrow, 18 to 26 degrees.", + delegation_id=event["delegation_id"]) +``` + +The current service accepts only one write-back per `delegation_id`; repeated +write-backs may return `CONFLICT`. Do not call the three write-back methods +back to back. `append_instruction` yields while waiting for user input, +`append_thinking` carries silent context, and `append_commentary` carries task +results; receiving an acknowledgment alone does not mean speech playback has +finished. Move slow agent processing off the receiving thread. + +--- + +## Important notes & limitations + +- **Reuse one session for multi-turn conversation**: after the first turn, + keep the send/receive loop running and continue sending the next turn's + audio on the same connection; do not call `end_session()` at the end of + every turn. The full example closes after one turn — it is only a minimal + integration. +- **There is no downstream-audio completion event**: neither + `session.usage.updated` nor `session.output_audio.interrupted` can serve as + an end-of-reply signal; for business completion confirmation, look at the + `session.closed` event type, not `session.status`. +- **Config updates do not rebuild the connection**: connection-level options + such as voice or transport may not support hot updates; when the server + returns `Changing connection options requires a new session`, reconnect and + re-initialize. +- **Reconnection requires re-initialization**: the SDK does not auto-reconnect + or resend; calling `connect()` again while open or closing raises + `RuntimeError`. After reconnecting you must send the configuration and + create a new `events()` iterator — iterators bound to the old connection + cannot be reused. +- **Every session must release its connection**: use `with` or + `finally: session.close()` as a safety net; with multiple threads, stop + sending and close the connection first, then wait for worker threads to + exit. When a business close confirmation is needed, stop the audio upstream + first, then send `end_session()` and keep receiving. +- **Handshake authentication failures**: 401 means the connection was never + established — check the API key, target address, region and workspace access + first; changing audio formats or send intervals will not help. When + troubleshooting with the service provider, share `exc.request_id`, never the + API key. +- **Troubleshoot by error stage**: a successful handshake does not mean the + frontend model is usable; handle `session.update` parameter errors and later + inference errors separately according to the server's `error.code` / + `message` — do not treat a single `UNSUPPORTED` as the whole model being + unavailable. \ No newline at end of file diff --git a/docs/en/guides/recipes.md b/docs/en/guides/recipes.md new file mode 100644 index 00000000..31f83766 --- /dev/null +++ b/docs/en/guides/recipes.md @@ -0,0 +1,124 @@ +--- +description: "Copy-paste recipes for every dashscope 2.0 capability: multimodal, images, videos, embeddings, rerank, speech, apps, files and models." +--- +# Capability recipes + +Short runnable snippets, one per capability. All of them assume an exported +`DASHSCOPE_API_KEY` (see [Quickstart](../quickstart.md)) and use the sync +client; `AsyncClient` mirrors every call with `await`. Response fields are +typed — the [API Reference](../reference/client.md) documents each one. + +## Multimodal understanding + +```python +from dashscope import Client + +with Client() as client: + resp = client.multimodal.chat.create( + model="qwen-vl-plus", + messages=[{ + "role": "user", + "content": [ + {"image": "https://example.com/dog_and_girl.jpeg"}, + {"text": "What is in this image?"}, + ], + }], + ) + print(resp.output_text) +``` + +## Image generation + +`generate()` submits the task and waits for it; the finished job carries +the result URLs. + +```python +job = client.images.generate( + model="wan2.2-t2i-flash", + prompt="A cat astronaut floating in space", +) +print(job.image_urls) +``` + +## Video generation + +```python +job = client.videos.generate( + model="wan2.2-t2v-plus", + prompt="A cat astronaut floating in space", +) +print(job.video_url) +``` + +## Text embeddings + +```python +resp = client.embeddings.create( + model="text-embedding-v4", + input=["hello world", "你好世界"], +) +print(len(resp.embeddings[0].embedding)) +``` + +## Rerank + +```python +resp = client.rerank.create( + model="gte-rerank-v2", + query="What is DashScope?", + documents=["DashScope is a model service.", "The weather is fine."], + top_n=2, +) +print(resp.results) +``` + +## Speech synthesis + +`synthesize()` returns the concatenated audio bytes. + +```python +audio = client.audio.tts.synthesize( + "Hello DashScope", + model="cosyvoice-v2", + voice="longxiaochun", +) +with open("out.mp3", "wb") as f: + f.write(audio) +``` + +## File recognition + +```python +for event in client.audio.asr.recognize_file( + "audio.pcm", + model="paraformer-realtime-v2", +): + print(event) +``` + +See [Audio](../reference/audio.md) and the +[Qwen Live guide](qwen-live-python-sdk.md) for realtime sessions. + +## Application call + +```python +resp = client.apps.create(app_id="your-app-id", prompt="Introduce yourself") +print(resp.text) +``` + +## File upload + +```python +file = client.files.upload(file_path="train.jsonl", purpose="fine-tune") +print(file.id) +``` + +## Model list + +```python +page = client.models.list() +print(len(page.items), "models available") +``` + +See [Client Resources](../reference/resources.md) for the full resource +surface, including batch jobs and fine-tunes. \ No newline at end of file diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 00000000..3f854942 --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,143 @@ +--- +description: "Official Python SDK for Alibaba Cloud Model Studio (DashScope): typed sync/async client, examples and feature overview." +--- +# DashScope Python SDK + +The `dashscope` SDK is the official Python client for +[Alibaba Cloud Model Studio (Bailian)](https://www.alibabacloud.com/help/en/model-studio/): +chat completions, multimodal understanding, embeddings, reranking, image and +video generation, speech synthesis & recognition, realtime voice, fine-tuning, +agentic RL, managed agents and applications. + +Version 2.0 is a typed, resource-style client — `dashscope.Client()` — modeled +on the ergonomics of the OpenAI SDK: one client holds a shared connection pool, +every capability hangs off it as a typed resource, responses are typed objects, +and failures raise exceptions by default. + +!!! tip "Where to start" + New here? Follow the [Quickstart](quickstart.md). Migrating existing + 1.x code? See [Migrating from 1.x](migration.md). + +## Features + +- **Typed resources** — `client.chat`, `client.images`, `client.audio`, … +- **Sync & async** — `AsyncClient` mirrors the sync surface. +- **Three protocols** — `native`, `openai`, `anthropic` on one client. +- **Text-like streaming** — `.text_stream`, `.reasoning_stream`. +- **Typed errors + self-diagnosis** and an offline **dev mock**. +- **A real CLI** and an optional interactive AI assistant. + +The full list: [Features](features.md). + +## Requirements + +- Python 3.9+ (the optional interactive assistant requires 3.10+). +- A Model Studio API key — create one in the + [Model Studio console](https://bailian.console.aliyun.com/), then export it: + +```shell +export DASHSCOPE_API_KEY="sk-..." +``` + +## Installation + +```shell +pip install -U dashscope +``` + +The base install covers SDK API calls, the `dashscope` CLI, Agentic RL +fine-tuning and the local tokenizer. Optional extras configure the interactive +AI assistant, e.g. `pip install "dashscope[acli]"` (see [CLI](cli.md)). + +## Examples + +### Create it + +```python +import dashscope + +client = dashscope.Client() # reads DASHSCOPE_API_KEY +``` + +### Run it + +```python +resp = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "Tell me a joke"}], +) +print(resp.output_text) +print(resp.usage.total_tokens) +``` + +Or the one-liner: `dashscope.chat("qwen-plus", "Tell me a joke")`. + +### Stream it + +```python +with client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "Write a haiku about the sea"}], + stream=True, +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + final = stream.get_final_message() +``` + +### Async it + +```python +import asyncio +import dashscope + +async def main(): + async with dashscope.AsyncClient() as client: + resp = await client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "Hello!"}], + ) + print(resp.output_text) + +asyncio.run(main()) +``` + +### Talk to it (realtime voice) + +`client.audio.live` runs full-duplex voice sessions over WebSocket — see the +[Qwen Live guide](guides/qwen-live-python-sdk.md) for a complete walkthrough. + +## Protocols + +The same call can speak three wire protocols: + +```python +client = dashscope.Client(protocol="openai") # or "native", "anthropic" +``` + +See [Protocols](reference/protocols.md). + +## Errors and diagnosis + +Failures raise typed `DashScopeError` subclasses carrying `code`, +`request_id` and the response body; opt-in local diagnosis adds structured +fix guidance on `error.diagnosis`. See [Errors](reference/errors.md) and +[Devkit](reference/devkit.md). + +## Legacy 1.x + +The complete 1.x surface still works from its historical import paths +(`from dashscope import Generation`), implemented by frozen facades. +See [Legacy 1.x](reference/legacy.md). + +## Dependencies + +The base install pulls in `requests`, `aiohttp`, `httpx` + `httpx-sse`, +`websocket-client`, `pydantic` (v2), `tenacity`, `tiktoken`, and `typer` + +`rich` for the CLI. Optional assistant extras are listed under +[Installation](#installation). + +## License + +This project is licensed under the +[Apache License 2.0](https://github.com/dashscope/dashscope-sdk-python/blob/main/LICENSE). \ No newline at end of file diff --git a/docs/en/migration.md b/docs/en/migration.md new file mode 100644 index 00000000..9275b38a --- /dev/null +++ b/docs/en/migration.md @@ -0,0 +1,89 @@ +--- +description: "Compare 1.x and 2.0 side by side and migrate existing code to the resource-style dashscope client." +--- +# Migrating from 1.x + +The 2.0 client replaces the 1.x module-level static classes, but the complete +1.x surface keeps working from its historical import paths. Migrate at your +own pace — this page maps old habits to new ones. + +## Side-by-side comparison + +| | 1.x | 2.0 | +|---|---|---| +| Entry point | Module-level static classes: `Generation.call(...)` | A resource-style client: `client.chat.completions.create(...)` | +| One-liner | — | `dashscope.chat("qwen-plus", "Tell me a joke")` | +| Response | Raw dict-like; check `status_code == HTTPStatus.OK` | Typed object; read `resp.output_text`, `resp.usage.total_tokens` | +| Errors | Inspect `resp.code` / `resp.message` by hand | Typed `DashScopeError` exceptions raised by default | +| Streaming | Generator of raw frames | `ChatStream` with `.text_stream`, `.reasoning_stream`, `.get_final_message()` | +| Protocols | DashScope native + a separate compatible-mode entry | One client speaks `native`, `openai`, or `anthropic` via `protocol=` | +| Async | Separate `Aio*` classes | `dashscope.AsyncClient()` mirrors the sync surface | +| Connections | A fresh session per call | One keep-alive pool per client, shared across resources | +| Config | Module globals (`dashscope.api_key`, `set_region`) | Layered: args → `dashscope.settings` → env → `~/.dashscope/config.toml` | + +## Call mapping + +| 1.x class | 2.0 resource | +| --- | --- | +| `Generation` / `AioGeneration` | `client.chat.completions` | +| `MultiModalConversation` | `client.multimodal` | +| `ImageSynthesis` / `ImageGeneration` | `client.images` | +| `VideoSynthesis` | `client.videos` | +| `TextEmbedding` / `BatchTextEmbedding` | `client.embeddings` | +| `MultiModalEmbedding` | `client.multimodal` (embeddings) | +| `TextReRank` | `client.rerank` | +| `SpeechSynthesizer` (tts / tts_v2) | `client.audio.tts` | +| `Recognition` / `Transcription` | `client.audio.asr` | +| `Files` | `client.files` | +| `Models` | `client.models` | +| `FineTunes` | `client.fine_tunes` | +| `Deployments` | `client.deployments` | +| `Application` | `client.apps` | + +Every 1.x class remains documented under [Legacy 1.x](reference/legacy.md). + +## Before / after + +1.x — call, then inspect the status by hand: + +```python +from http import HTTPStatus +from dashscope import Generation + +resp = Generation.call( + model="qwen-plus", + messages=[{"role": "user", "content": "Hello!"}], +) +if resp.status_code != HTTPStatus.OK: + print(resp.code, resp.message) +else: + print(resp.output.text) +``` + +2.0 — typed response, exceptions on failure: + +```python +from dashscope import Client, DashScopeError + +try: + with Client() as client: + resp = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "Hello!"}], + ) + print(resp.output_text) +except DashScopeError as exc: + print(exc.code, exc.message) +``` + +## What stays the same + +- Import paths: `from dashscope import Generation` still works (frozen facade). +- The `DASHSCOPE_API_KEY` environment variable and the console-issued keys. +- Model names and request payloads — the wire contract is unchanged for the + native protocol. + +!!! tip "Migrate incrementally" + Both surfaces coexist in one process. Move call sites one by one; there + is no flag day. See [Release Notes](release-notes.md) for what each + 2.x release changed. \ No newline at end of file diff --git a/docs/en/quickstart.md b/docs/en/quickstart.md new file mode 100644 index 00000000..dce7aa61 --- /dev/null +++ b/docs/en/quickstart.md @@ -0,0 +1,147 @@ +--- +description: "Install dashscope, configure your API key and make your first chat completion in minutes." +--- +# Quickstart + +The dashscope 2.0 API centers on a typed [Client](reference/client.md) (and its +async twin `AsyncClient`) with resource namespaces such as `client.chat`, +`client.images` and `client.audio`. This page gets you from install to your +first chat completion. + +## Installation + +Python 3.9 or newer is required. + +```bash +python -m pip install -U dashscope +``` + +## Configure your API key + +The recommended way is the `DASHSCOPE_API_KEY` environment variable — never +hard-code keys in source files: + +```bash +export DASHSCOPE_API_KEY="" +``` + +Alternatively, persist the key once with `dashscope.save_api_key("sk-xxx")` +(writes `~/.dashscope/api_key`), or assign it at runtime through +`dashscope.settings.api_key`. + +Configuration is resolved in this order, first match wins: + +1. Explicit `Client(...)` arguments +2. Process-level `dashscope.settings` +3. Environment variables (`DASHSCOPE_API_KEY`, `DASHSCOPE_BASE_URL`, ...) +4. `config.toml` +5. The API key file + +!!! tip "CI and containers" + Inject `DASHSCOPE_API_KEY` as a secret environment variable in CI; + `save_api_key` is meant for interactive local machines only. + +## One-call chat + +For scripts and notebooks, `dashscope.chat` manages a client for you: + +```python +import dashscope + +resp = dashscope.chat("qwen-plus", "Tell me a joke") +print(resp.output_text) +``` + +Extra keyword arguments are forwarded to `client.chat.completions.create`. + +## Use the Client + +```python +import dashscope + +client = dashscope.Client() # reads DASHSCOPE_API_KEY +resp = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "Hello!"}], +) +print(resp.output_text) +``` + +`Client` owns an HTTP connection pool; close it when done, or use it as a +context manager: + +```python +with dashscope.Client() as client: + resp = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "Hello!"}], + ) +``` + +### Streaming + +Pass `stream=True` and iterate over the chunks: + +```python +with dashscope.Client() as client: + stream = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "Write a haiku about the sea."}], + stream=True, + ) + for chunk in stream: + if chunk.choices: + print(chunk.choices[0].delta.content or "", end="", flush=True) +``` + +### Async + +```python +import asyncio +import dashscope + + +async def main(): + async with dashscope.AsyncClient() as client: + resp = await client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "Hello!"}], + ) + print(resp.output_text) + + +asyncio.run(main()) +``` + +## Error handling + +All 2.0 failures raise subclasses of +[DashScopeError][dashscope.errors.DashScopeError] carrying `code`, +`status_code`, `request_id` and the response `body`: + +```python +from dashscope import Client, DashScopeError + +try: + with Client() as client: + client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "Hi"}], + ) +except DashScopeError as exc: + print(exc.code, exc.status_code, exc.request_id, exc.message) +``` + +See [Errors](reference/errors.md) for the full hierarchy (rate limits, +authentication, timeouts, WebSocket errors, ...). + +## Next steps + +- [Client & Configuration](reference/client.md) — `Client` / `AsyncClient` + constructor options, `Config` / `Settings`, region switching. +- [Chat](reference/chat.md) — chat completions, streaming and response models. +- [Audio](reference/audio.md) — TTS, ASR, realtime and Qwen Live sessions; see + the [Qwen Live guide](guides/qwen-live-python-sdk.md) for a full walkthrough. +- [Resources](reference/resources.md) — embeddings, rerank, images, videos, + files, models, fine-tunes, deployments, apps and more. +- [Types](reference/types.md) — shared message / response / pagination models. \ No newline at end of file diff --git a/docs/en/reference/agentic-rl.md b/docs/en/reference/agentic-rl.md new file mode 100644 index 00000000..aee3a4a2 --- /dev/null +++ b/docs/en/reference/agentic-rl.md @@ -0,0 +1,57 @@ +--- +description: "API reference for Agentic RL fine-tuning: submission entry point and reward/rollout authoring API." +--- +# Agentic RL Fine-tuning + +`dashscope.applications.finetune` hosts the Agentic RL fine-tuning workflow: +submit training jobs built from your own rollout / reward functions. Job, +dataset and function management on the service side lives under `client.rl` +(see [Resources](resources.md#reinforcement-learning)); this page covers the +local submission entry point and the authoring API for reward / rollout +components. + +## Submission entry point + +::: dashscope.applications.finetune.agentic_rl.AgenticRL + +::: dashscope.applications.finetune.agentic_rl.SubmitOutput + +::: dashscope.applications.finetune.agentic_rl.SubmitResult + +## Function decorators + +Register plain Python functions as rollout / reward components: + +::: dashscope.applications.finetune.reinforcement.component.reward_func + +::: dashscope.applications.finetune.reinforcement.component.sub_reward_func + +::: dashscope.applications.finetune.reinforcement.component.aggregate_func + +## Data models + +::: dashscope.applications.finetune.reinforcement.component.RolloutInput + +::: dashscope.applications.finetune.reinforcement.component.RolloutOutput + +::: dashscope.applications.finetune.reinforcement.component.RewardInput + +::: dashscope.applications.finetune.reinforcement.component.Reward + +::: dashscope.applications.finetune.reinforcement.component.RewardOutput + +::: dashscope.applications.finetune.reinforcement.component.AgentOutput + +::: dashscope.applications.finetune.reinforcement.component.Task + +::: dashscope.applications.finetune.reinforcement.component.TaskStatus + +## Processor base classes & demos + +::: dashscope.applications.finetune.reinforcement.component.AbstractRolloutProcessor + +::: dashscope.applications.finetune.reinforcement.component.AbstractRewardProcessor + +::: dashscope.applications.finetune.reinforcement.component.DemoRolloutProcessor + +::: dashscope.applications.finetune.reinforcement.component.DemoRewardProcessor \ No newline at end of file diff --git a/docs/en/reference/agentstudio.md b/docs/en/reference/agentstudio.md new file mode 100644 index 00000000..eb795700 --- /dev/null +++ b/docs/en/reference/agentstudio.md @@ -0,0 +1,243 @@ +--- +description: "API reference for the AgentStudio sub-SDK: managed agents, sessions, deployments, memory and vaults." +--- +# AgentStudio + +`dashscope.applications.agentstudio` is the sub-SDK for the AgentStudio +managed-agent API: agents, sessions, events, environments, deployments, +memory, skills, vaults, security and webhooks. All resources are reached +through its own client: + +```python +from dashscope.applications.agentstudio import Client +from dashscope.applications.agentstudio import user_message + +client = Client(api_key="sk-xxx") +agent = client.agents.create(name="demo", model="qwen-plus") +session = client.sessions.create(agent=agent.id) +client.sessions.events.send(session.id, [user_message("Hello!")]) +with client.sessions.events.stream(session.id) as stream: + for event in stream: + print(event.type) + if event.type == "session_status": + break +``` + +Every resource class has an async twin (`AsyncAgents`, `AsyncSessions`, ...) +used the same way through `AsyncClient`. + +## Clients + +::: dashscope.applications.agentstudio.Client + +::: dashscope.applications.agentstudio.AsyncClient + +## Agents & sessions + +::: dashscope.applications.agentstudio.resources.agents.Agents + +::: dashscope.applications.agentstudio.resources.agents.AsyncAgents + +::: dashscope.applications.agentstudio.resources.sessions.Sessions + +::: dashscope.applications.agentstudio.resources.sessions.AsyncSessions + +::: dashscope.applications.agentstudio.resources.session_events.SessionEvents + +::: dashscope.applications.agentstudio.resources.session_events.AsyncSessionEvents + +::: dashscope.applications.agentstudio.resources.session_threads.SessionThreads + +::: dashscope.applications.agentstudio.resources.session_threads.AsyncSessionThreads + +::: dashscope.applications.agentstudio.resources.session_threads.SessionThreadEvents + +::: dashscope.applications.agentstudio.resources.session_threads.AsyncSessionThreadEvents + +::: dashscope.applications.agentstudio.resources.session_resources.SessionResources + +::: dashscope.applications.agentstudio.resources.session_resources.AsyncSessionResources + +## Environments & deployments + +::: dashscope.applications.agentstudio.resources.environments.Environments + +::: dashscope.applications.agentstudio.resources.environments.AsyncEnvironments + +::: dashscope.applications.agentstudio.resources.deployments.Deployments + +::: dashscope.applications.agentstudio.resources.deployments.AsyncDeployments + +::: dashscope.applications.agentstudio.resources.deployments.DeploymentRuns + +::: dashscope.applications.agentstudio.resources.deployments.AsyncDeploymentRuns + +## Files + +::: dashscope.applications.agentstudio.resources.files.Files + +::: dashscope.applications.agentstudio.resources.files.AsyncFiles + +## Memory + +::: dashscope.applications.agentstudio.resources.memory_stores.MemoryStores + +::: dashscope.applications.agentstudio.resources.memory_stores.AsyncMemoryStores + +::: dashscope.applications.agentstudio.resources.memory_stores.Memories + +::: dashscope.applications.agentstudio.resources.memory_stores.AsyncMemories + +::: dashscope.applications.agentstudio.resources.memory_stores.MemoryVersions + +::: dashscope.applications.agentstudio.resources.memory_stores.AsyncMemoryVersions + +## Skills + +::: dashscope.applications.agentstudio.resources.skills.Skills + +::: dashscope.applications.agentstudio.resources.skills.AsyncSkills + +::: dashscope.applications.agentstudio.resources.skills.SkillVersions + +::: dashscope.applications.agentstudio.resources.skills.AsyncSkillVersions + +## Vaults & credentials + +::: dashscope.applications.agentstudio.resources.vaults.Vaults + +::: dashscope.applications.agentstudio.resources.vaults.AsyncVaults + +::: dashscope.applications.agentstudio.resources.vaults.Credentials + +::: dashscope.applications.agentstudio.resources.vaults.AsyncCredentials + +## Security & webhooks + +::: dashscope.applications.agentstudio.resources.security.Security + +::: dashscope.applications.agentstudio.resources.security.AsyncSecurity + +::: dashscope.applications.agentstudio.resources.webhook_endpoints.WebhookEndpoints + +::: dashscope.applications.agentstudio.resources.webhook_endpoints.AsyncWebhookEndpoints + +## Client event helpers + +::: dashscope.applications.agentstudio.user_message + +::: dashscope.applications.agentstudio.user_interrupt + +::: dashscope.applications.agentstudio.user_tool_result + +::: dashscope.applications.agentstudio.user_custom_tool_result + +::: dashscope.applications.agentstudio.user_tool_approval_response + +::: dashscope.applications.agentstudio.user_define_outcome + +## Core types + +::: dashscope.applications.agentstudio.Message + +::: dashscope.applications.agentstudio.ServerEvent + +::: dashscope.applications.agentstudio.SessionResource + +::: dashscope.applications.agentstudio.StopReason + +::: dashscope.applications.agentstudio.Memory + +::: dashscope.applications.agentstudio.MemoryStore + +::: dashscope.applications.agentstudio.MemoryVersion + +::: dashscope.applications.agentstudio.PermissionPolicy + +::: dashscope.applications.agentstudio.SecurityAlert + +::: dashscope.applications.agentstudio.SecurityAlertList + +::: dashscope.applications.agentstudio.SecurityOverview + +## Request parameter types + +::: dashscope.applications.agentstudio.AgentCreateParams + +::: dashscope.applications.agentstudio.AgentUpdateParams + +::: dashscope.applications.agentstudio.SessionCreateParams + +::: dashscope.applications.agentstudio.SessionUpdateParams + +::: dashscope.applications.agentstudio.SessionEventSendParams + +::: dashscope.applications.agentstudio.EnvironmentCreateParams + +::: dashscope.applications.agentstudio.EnvironmentUpdateParams + +::: dashscope.applications.agentstudio.DeploymentCreateParams + +::: dashscope.applications.agentstudio.DeploymentUpdateParams + +::: dashscope.applications.agentstudio.WebhookEndpointCreateParams + +::: dashscope.applications.agentstudio.WebhookEndpointUpdateParams + +::: dashscope.applications.agentstudio.WebhookEventListParams + +## Constants & enums + +::: dashscope.applications.agentstudio.SessionStatus + +::: dashscope.applications.agentstudio.SSEEventType + +::: dashscope.applications.agentstudio.StopReasonType + +::: dashscope.applications.agentstudio.PermissionPolicyType + +::: dashscope.applications.agentstudio.WebhookStatus + +::: dashscope.applications.agentstudio.WebhookEventType + +::: dashscope.applications.agentstudio.WebhookDeliveryStatus + +::: dashscope.applications.agentstudio.WebhookDisabledReason + +## Pagination, transport & exceptions + +::: dashscope.applications.agentstudio.CursorPage + +::: dashscope.applications.agentstudio.AsyncCursorPage + +::: dashscope.applications.agentstudio.RequestOptions + +::: dashscope.applications.agentstudio.APIResponse + +::: dashscope.applications.agentstudio.AgentStudioError + +::: dashscope.applications.agentstudio.APIConnectionError + +::: dashscope.applications.agentstudio.APITimeoutError + +::: dashscope.applications.agentstudio.APIStatusError + +::: dashscope.applications.agentstudio.AuthenticationError + +::: dashscope.applications.agentstudio.PermissionDeniedError + +::: dashscope.applications.agentstudio.NotFoundError + +::: dashscope.applications.agentstudio.ConflictError + +::: dashscope.applications.agentstudio.InvalidRequestError + +::: dashscope.applications.agentstudio.RateLimitError + +::: dashscope.applications.agentstudio.OverloadedError + +::: dashscope.applications.agentstudio.InternalServerError + +::: dashscope.applications.agentstudio.StreamError + +::: dashscope.applications.agentstudio.StreamClosedError \ No newline at end of file diff --git a/docs/en/reference/audio.md b/docs/en/reference/audio.md new file mode 100644 index 00000000..b9b14c77 --- /dev/null +++ b/docs/en/reference/audio.md @@ -0,0 +1,82 @@ +--- +description: "API reference for speech synthesis, recognition, realtime sessions and voice customization." +--- +# Audio + +`client.audio` groups speech synthesis (TTS), recognition (ASR), realtime +WebSocket sessions and Qwen Live, plus voice/vocabulary customization. + +## Audio surface + +::: dashscope.resources.audio.Audio + +::: dashscope.resources.audio.AsyncAudio + +## Speech synthesis (TTS) + +::: dashscope.resources.audio.tts.Tts + +::: dashscope.resources.audio.tts.SynthesisSession + +::: dashscope.resources.audio.http_tts.HttpTts + +::: dashscope.resources.audio.http_tts.AsyncHttpTts + +::: dashscope.resources.audio.http_tts.HttpSynthesis + +::: dashscope.resources.audio.http_tts.HttpSynthesisChunk + +::: dashscope.resources.audio.http_tts.HttpSynthesisStream + +## Recognition (ASR) + +::: dashscope.resources.audio.asr.Asr + +::: dashscope.resources.audio.asr.AsyncAsr + +::: dashscope.resources.audio.asr.Recognition + +::: dashscope.resources.audio.asr.TranscriptionJobs + +::: dashscope.resources.audio.asr.AsyncTranscriptionJobs + +::: dashscope.resources.audio.asr.RecognitionResult + +## Realtime & Qwen Live + +See the [Qwen Live guide](../guides/qwen-live-python-sdk.md) for a full +walkthrough of `client.audio.live`. + +::: dashscope.resources.audio.realtime.Realtime + +::: dashscope.resources.audio.realtime.RealtimeSession + +::: dashscope.resources.audio.live.Live + +::: dashscope.resources.audio.live.LiveSession + +## Voice & vocabulary customization + +::: dashscope.resources.audio.customization.Voices + +::: dashscope.resources.audio.customization.Voice + +::: dashscope.resources.audio.customization.VoiceList + +::: dashscope.resources.audio.customization.VoiceDesign + +::: dashscope.resources.audio.customization.DesignedVoice + +::: dashscope.resources.audio.customization.DesignedVoiceList + +::: dashscope.resources.audio.customization.Vocabularies + +::: dashscope.resources.audio.customization.Vocabulary + +::: dashscope.resources.audio.customization.VocabularyList + +::: dashscope.resources.audio.phrases.Phrases + +::: dashscope.resources.audio.phrases.Phrase + +::: dashscope.resources.audio.phrases.PhraseList \ No newline at end of file diff --git a/docs/en/reference/chat.md b/docs/en/reference/chat.md new file mode 100644 index 00000000..ce76d8ad --- /dev/null +++ b/docs/en/reference/chat.md @@ -0,0 +1,28 @@ +--- +description: "API reference for chat completions: sync/async resources and streaming classes." +--- +# Chat + +`client.chat.completions` creates chat completions, with or without streaming. +Response models live in [Types](types.md). + +## Resource classes + +::: dashscope.resources.chat.Chat + +::: dashscope.resources.chat.AsyncChat + +::: dashscope.resources.chat.completions.Completions + +::: dashscope.resources.chat.completions.AsyncCompletions + +::: dashscope.resources.chat.completions.ChatStream + +::: dashscope.resources.chat.completions.AsyncChatStream + +## See also + +- [ChatCompletion][dashscope.types.completions.ChatCompletion] / + [ChatCompletionChunk][dashscope.types.completions.ChatCompletionChunk] — + response models. +- [Types](types.md) — messages, choices, deltas and usage. \ No newline at end of file diff --git a/docs/en/reference/client.md b/docs/en/reference/client.md new file mode 100644 index 00000000..67c6f784 --- /dev/null +++ b/docs/en/reference/client.md @@ -0,0 +1,40 @@ +--- +description: "API reference for dashscope Client, AsyncClient, Config, Settings and module-level helpers." +--- +# Client & Configuration + +The 2.0 entry points: `Client` (sync) and `AsyncClient` (async), plus +configuration and module-level helpers. + +!!! note "Async scope" + `AsyncClient` mirrors the sync surface except the duplex audio + WebSocket sessions, which remain sync-only. + +## Clients + +::: dashscope.client.Client + +::: dashscope.client.AsyncClient + +## Configuration + +::: dashscope._config.Config + +::: dashscope._config.Settings + +## Top-level helpers + +::: dashscope.chat + +::: dashscope.set_region + +::: dashscope.save_api_key + +## WebSocket transport + +Low-level WebSocket primitives exported from the package root, used by the +realtime audio sessions and available for custom inference tasks: + +::: dashscope.transport.ws_connection.WsConnection + +::: dashscope.transport.ws_connection.WsTask diff --git a/docs/en/reference/devkit.md b/docs/en/reference/devkit.md new file mode 100644 index 00000000..f8e5fa49 --- /dev/null +++ b/docs/en/reference/devkit.md @@ -0,0 +1,43 @@ +--- +description: "API reference for dev mock modes and local self-diagnosis." +--- +# Devkit (Mock & Diagnosis) + +`dashscope.devkit` provides two opt-in developer aids with near-zero overhead +when disabled. Nothing here is imported on the production success path. + +- **Dev mock** — `static` / `replay` / `record` modes that exercise the full + 2.0 HTTP request path without spending cloud tokens. HTTP only; the + WebSocket transport is not covered. Activate in code with + `dashscope.enable_dev_mock(...)` or via `DASHSCOPE_DEV_MOCK=`. +- **Self-diagnosis** — a local, bilingual rule table that turns a failed call + into structured fix guidance, surfaced on `DashScopeError.diagnosis`. + +The root module forwards the mock switches: `dashscope.enable_dev_mock`, +`dashscope.disable_dev_mock` and `dashscope.dev_mock_active`. + +!!! tip "Sharing recordings" + `record` mode writes real responses to disk; register a redactor with + `set_redactor` before sharing fixtures. + +## Dev mock switches + +::: dashscope.devkit.enable_dev_mock + +::: dashscope.devkit.disable_dev_mock + +::: dashscope.devkit.is_active + +::: dashscope.devkit.mock.DevMockMiss + +::: dashscope.devkit.mock.set_redactor + +## Self-diagnosis + +::: dashscope.devkit.diagnosis.Diagnosis + +::: dashscope.devkit.diagnosis.diagnose + +::: dashscope.devkit.diagnosis.render + +::: dashscope.devkit.diagnosis.install_excepthook \ No newline at end of file diff --git a/docs/en/reference/errors.md b/docs/en/reference/errors.md new file mode 100644 index 00000000..e0029006 --- /dev/null +++ b/docs/en/reference/errors.md @@ -0,0 +1,58 @@ +--- +description: "API reference for the DashScopeError exception hierarchy and error codes." +--- +# Errors + +All 2.0 exceptions inherit from `DashScopeError` and carry `message`, `code`, +`status_code`, `request_id`, `body` and `headers`. Catch the base class to +handle any SDK or API failure, or catch specific subclasses for finer control. + +## Base class & error codes + +::: dashscope.errors.DashScopeError + +::: dashscope.errors.ErrorCode + +::: dashscope.errors.SdkError + +## Transport & validation errors + +::: dashscope.errors.APIConnectionError + +::: dashscope.errors.APITimeoutError + +::: dashscope.errors.APIResponseValidationError + +## HTTP status errors + +::: dashscope.errors.APIStatusError + +::: dashscope.errors.BadRequestError + +::: dashscope.errors.AuthenticationError + +::: dashscope.errors.PermissionDeniedError + +::: dashscope.errors.NotFoundError + +::: dashscope.errors.RequestTooLargeError + +::: dashscope.errors.RateLimitError + +::: dashscope.errors.InternalServerError + +::: dashscope.errors.ServiceUnavailableError + +::: dashscope.errors.GatewayTimeoutError + +::: dashscope.errors.ContentFilterError + +## WebSocket errors + +::: dashscope.errors.WsEventError + +::: dashscope.errors.WsStateError + +::: dashscope.errors.WsQueueCapacityExceededError + +::: dashscope.errors.WsBinaryOwnerConflictError \ No newline at end of file diff --git a/docs/en/reference/legacy.md b/docs/en/reference/legacy.md new file mode 100644 index 00000000..746ccba2 --- /dev/null +++ b/docs/en/reference/legacy.md @@ -0,0 +1,183 @@ +--- +description: "Frozen 1.x API surface archived under dashscope.legacy_1x, kept for backward compatibility." +status: deprecated +--- +# Legacy 1.x API + +The 1.x API classes are archived under `dashscope.legacy_1x` and remain +importable from the `dashscope` root module for backward compatibility +(`from dashscope import Generation` still works). The layer is frozen: it +receives no new features. New code should use the 2.0 [Client](client.md). + +!!! warning "Frozen layer" + The 1.x surface receives no new features. `Assistants` / `Threads` + additionally emit `DeprecationWarning` on access. + +## Text generation + +::: dashscope.legacy_1x.aigc.generation.Generation + +::: dashscope.legacy_1x.aigc.generation.AioGeneration + +::: dashscope.legacy_1x.aigc.code_generation.CodeGeneration + +::: dashscope.legacy_1x.aigc.conversation.Conversation + +::: dashscope.legacy_1x.aigc.conversation.History + +::: dashscope.legacy_1x.aigc.conversation.HistoryItem + +## Multimodal conversation + +::: dashscope.legacy_1x.aigc.multimodal_conversation.MultiModalConversation + +::: dashscope.legacy_1x.aigc.multimodal_conversation.AioMultiModalConversation + +## Image & video synthesis + +::: dashscope.legacy_1x.aigc.image_synthesis.ImageSynthesis + +::: dashscope.legacy_1x.aigc.image_synthesis.AioImageSynthesis + +::: dashscope.legacy_1x.aigc.image_generation.ImageGeneration + +::: dashscope.legacy_1x.aigc.image_generation.AioImageGeneration + +::: dashscope.legacy_1x.aigc.video_synthesis.VideoSynthesis + +::: dashscope.legacy_1x.aigc.video_synthesis.AioVideoSynthesis + +## Embeddings + +::: dashscope.legacy_1x.embeddings.text_embedding.TextEmbedding + +::: dashscope.legacy_1x.embeddings.batch_text_embedding.BatchTextEmbedding + +::: dashscope.legacy_1x.embeddings.batch_text_embedding_response.BatchTextEmbeddingResponse + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.MultiModalEmbedding + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.AioMultiModalEmbedding + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.MultiModalEmbeddingItemText + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.MultiModalEmbeddingItemImage + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.MultiModalEmbeddingItemAudio + +## Rerank + +::: dashscope.legacy_1x.rerank.TextReRank + +::: dashscope.legacy_1x.rerank.AioTextReRank + +## NLP understanding + +::: dashscope.legacy_1x.nlp.understanding.Understanding + +## Application calls + +::: dashscope.legacy_1x.app.application.Application + +::: dashscope.legacy_1x.app.application.ApplicationResponse + +## Speech synthesis (1.x) + +::: dashscope.legacy_1x.audio.tts.speech_synthesizer.SpeechSynthesizer + +::: dashscope.legacy_1x.audio.tts.speech_synthesizer.ResultCallback + +::: dashscope.legacy_1x.audio.tts.speech_synthesizer.SpeechSynthesisResult + +::: dashscope.legacy_1x.audio.http_tts.http_speech_synthesizer.HttpSpeechSynthesizer + +::: dashscope.legacy_1x.audio.tts_v2.speech_synthesizer.SpeechSynthesizer + +::: dashscope.legacy_1x.audio.tts_v2.speech_synthesizer.ResultCallback + +::: dashscope.legacy_1x.audio.tts_v2.enrollment.VoiceEnrollmentService + +::: dashscope.legacy_1x.audio.qwen_tts.speech_synthesizer.SpeechSynthesizer + +::: dashscope.legacy_1x.audio.qwen_tts_realtime.qwen_tts_realtime.QwenTtsRealtime + +::: dashscope.legacy_1x.audio.qwen_tts_realtime.qwen_tts_realtime.QwenTtsRealtimeCallback + +## Speech recognition (1.x) + +::: dashscope.legacy_1x.audio.asr.recognition.Recognition + +::: dashscope.legacy_1x.audio.asr.recognition.RecognitionCallback + +::: dashscope.legacy_1x.audio.asr.recognition.RecognitionResult + +::: dashscope.legacy_1x.audio.asr.transcription.Transcription + +::: dashscope.legacy_1x.audio.asr.asr_phrase_manager.AsrPhraseManager + +::: dashscope.legacy_1x.audio.asr.translation_recognizer.TranslationRecognizerRealtime + +::: dashscope.legacy_1x.audio.asr.translation_recognizer.TranslationRecognizerChat + +::: dashscope.legacy_1x.audio.asr.translation_recognizer.TranslationRecognizerCallback + +::: dashscope.legacy_1x.audio.qwen_asr.qwen_transcription.QwenTranscription + +## Omni realtime (1.x) + +::: dashscope.legacy_1x.audio.qwen_omni.omni_realtime.OmniRealtimeConversation + +::: dashscope.legacy_1x.audio.qwen_omni.omni_realtime.OmniRealtimeCallback + +## Files & models (1.x) + +::: dashscope.legacy_1x.files.Files + +::: dashscope.legacy_1x.models.Models + +## Fine-tuning & deployments (1.x) + +::: dashscope.legacy_1x.finetune.finetunes.FineTunes + +::: dashscope.legacy_1x.finetune.deployments.Deployments + +## Tokenizers + +::: dashscope.legacy_1x.tokenizers.Tokenization + +::: dashscope.legacy_1x.tokenizers.Tokenizer + +::: dashscope.legacy_1x.tokenizers.get_tokenizer + +::: dashscope.legacy_1x.tokenizers.list_tokenizers + +## Assistants & Threads (deprecated) + +The Assistants API is deprecated; accessing these names emits a +`DeprecationWarning`. + +::: dashscope.legacy_1x.assistants.assistants.Assistants + +::: dashscope.legacy_1x.assistants.assistant_types.Assistant + +::: dashscope.legacy_1x.threads.threads.Threads + +::: dashscope.legacy_1x.threads.thread_types.Thread + +::: dashscope.legacy_1x.threads.thread_types.ThreadMessage + +::: dashscope.legacy_1x.threads.messages.messages.Messages + +::: dashscope.legacy_1x.threads.runs.runs.Runs + +::: dashscope.legacy_1x.threads.thread_types.Run + +::: dashscope.legacy_1x.threads.runs.steps.Steps + +::: dashscope.legacy_1x.threads.thread_types.RunStep + +## Shared session helpers + +::: dashscope.legacy_1x.api_entities.http_request.close_shared_sync_session + +::: dashscope.legacy_1x.api_entities.aio_session.close_shared_aio_session \ No newline at end of file diff --git a/docs/en/reference/protocols.md b/docs/en/reference/protocols.md new file mode 100644 index 00000000..a9770900 --- /dev/null +++ b/docs/en/reference/protocols.md @@ -0,0 +1,33 @@ +--- +description: "API reference for native, OpenAI-compatible and Anthropic-compatible protocol adapters." +--- +# Protocol Adapters + +`dashscope.protocols` translates chat requests and responses between wire +protocols, so the same `client.chat.completions` call can speak the DashScope +native protocol, the OpenAI-compatible protocol or the Anthropic-compatible +protocol. Select one with `Client(protocol="openai")` (or the `protocol` +setting / `DASHSCOPE_PROTOCOL` environment variable); valid values are +`native`, `openai` and `anthropic`. + +!!! tip "Precedence" + An explicit `Client(protocol=...)` argument wins over the `protocol` + setting, which wins over `DASHSCOPE_PROTOCOL`. + +## Base contract + +::: dashscope.protocols.base.ChatProtocol + +::: dashscope.protocols.base.ChatRequest + +## Adapters + +::: dashscope.protocols.native.NativeProtocol + +::: dashscope.protocols.openai.OpenAIProtocol + +::: dashscope.protocols.anthropic.AnthropicProtocol + +## Registry + +::: dashscope.protocols.get_protocol \ No newline at end of file diff --git a/docs/en/reference/resources.md b/docs/en/reference/resources.md new file mode 100644 index 00000000..05b82ef3 --- /dev/null +++ b/docs/en/reference/resources.md @@ -0,0 +1,217 @@ +--- +description: "API reference for client resource namespaces: embeddings, images, videos, files, fine-tunes and more." +--- +# Client Resources + +Resource namespaces mounted on `Client` and `AsyncClient`. +Each section lists the sync and async classes and their response models. + +## Embeddings + +`client.embeddings` — text embedding calls and batch jobs. + +::: dashscope.resources.embeddings.Embeddings + +::: dashscope.resources.embeddings.AsyncEmbeddings + +::: dashscope.resources.embeddings.EmbeddingJobs + +::: dashscope.resources.embeddings.AsyncEmbeddingJobs + +::: dashscope.resources.embeddings.Embedding + +::: dashscope.resources.embeddings.EmbeddingResponse + +## Multimodal + +`client.multimodal` — multimodal chat and embeddings. + +::: dashscope.resources.multimodal.Multimodal + +::: dashscope.resources.multimodal.AsyncMultimodal + +::: dashscope.resources.multimodal.chat.MultimodalChat + +::: dashscope.resources.multimodal.chat.AsyncMultimodalChat + +::: dashscope.resources.multimodal.embeddings.MultimodalEmbeddings + +::: dashscope.resources.multimodal.embeddings.AsyncMultimodalEmbeddings + +::: dashscope.resources.multimodal.embeddings.EmbeddingItem + +## Rerank + +`client.rerank` — document reranking. + +::: dashscope.resources.rerank.Rerank + +::: dashscope.resources.rerank.AsyncRerank + +::: dashscope.resources.rerank.RerankResponse + +::: dashscope.resources.rerank.RerankResult + +::: dashscope.resources.rerank.RerankDocument + +## Images + +`client.images` — image generation jobs. + +::: dashscope.resources.images.Images + +::: dashscope.resources.images.AsyncImages + +::: dashscope.resources.images.ImageJobs + +::: dashscope.resources.images.AsyncImageJobs + +## Videos + +`client.videos` — video generation jobs. + +::: dashscope.resources.videos.Videos + +::: dashscope.resources.videos.AsyncVideos + +::: dashscope.resources.videos.VideoJobs + +::: dashscope.resources.videos.AsyncVideoJobs + +## Files + +`client.files` — file upload, listing and deletion. + +::: dashscope.resources.files.Files + +::: dashscope.resources.files.AsyncFiles + +::: dashscope.resources.files.File + +::: dashscope.resources.files.FileList + +::: dashscope.resources.files.DeletionStatus + +## Models + +`client.models` — the model catalog. + +::: dashscope.resources.models.Models + +::: dashscope.resources.models.AsyncModels + +::: dashscope.resources.models.Model + +::: dashscope.resources.models.ModelList + +## Fine-tunes + +`client.fine_tunes` — fine-tuning jobs, logs and events. + +::: dashscope.resources.fine_tunes.FineTunes + +::: dashscope.resources.fine_tunes.AsyncFineTunes + +::: dashscope.resources.fine_tunes.FineTune + +::: dashscope.resources.fine_tunes.FineTuneList + +::: dashscope.resources.fine_tunes.JobLogs + +::: dashscope.resources.fine_tunes.FineTuneEvent + +## Deployments + +`client.deployments` — model deployments. + +::: dashscope.resources.deployments.Deployments + +::: dashscope.resources.deployments.AsyncDeployments + +::: dashscope.resources.deployments.Deployment + +::: dashscope.resources.deployments.DeploymentList + +::: dashscope.resources.deployments.DeploymentEvent + +## Apps + +`client.apps` — application completions (agents / workflows). + +::: dashscope.resources.apps.Apps + +::: dashscope.resources.apps.AsyncApps + +::: dashscope.resources.apps.AppCompletions + +::: dashscope.resources.apps.AsyncAppCompletions + +::: dashscope.resources.apps.AppCompletion + +::: dashscope.resources.apps.AppStream + +::: dashscope.resources.apps.AsyncAppStream + +::: dashscope.resources.apps.AppUsage + +::: dashscope.resources.apps.Thought + +::: dashscope.resources.apps.DocReference + +::: dashscope.resources.apps.WorkflowMessage + +## TingWu + +`client.tingwu` — meeting transcription and analysis. + +::: dashscope.resources.tingwu.TingWu + +::: dashscope.resources.tingwu.AsyncTingWu + +::: dashscope.resources.tingwu.TingWuRealtime + +::: dashscope.resources.tingwu.TingWuResult + +## Decision + +`client.decision` — structured decision / judging calls. + +::: dashscope.resources.decision.Decision + +::: dashscope.resources.decision.AsyncDecision + +::: dashscope.resources.decision.DecisionResponse + +::: dashscope.resources.decision.DecisionAnswer + +::: dashscope.resources.decision.ChoiceQuestion + +::: dashscope.resources.decision.NoulQuestion + +::: dashscope.resources.decision.ScoreQuestion + +## Tokenization + +`client.tokenization` — token counting. + +::: dashscope.resources.tokenization.Tokenization + +::: dashscope.resources.tokenization.AsyncTokenization + +::: dashscope.resources.tokenization.TokenCount + +## Reinforcement learning + +`client.rl` — agentic RL datasets, functions and jobs. + +::: dashscope.resources.reinforcement_learning.Rl + +::: dashscope.resources.reinforcement_learning.AsyncRl + +::: dashscope.resources.reinforcement_learning.RlJobs + +::: dashscope.resources.reinforcement_learning.AsyncRlJobs + +::: dashscope.resources.reinforcement_learning.RegisteredFunctions + +::: dashscope.resources.reinforcement_learning.UploadedData \ No newline at end of file diff --git a/docs/en/reference/types.md b/docs/en/reference/types.md new file mode 100644 index 00000000..11488ac2 --- /dev/null +++ b/docs/en/reference/types.md @@ -0,0 +1,62 @@ +--- +description: "API reference for shared pydantic models: messages, completions, pagination and helpers." +--- +# Types + +Shared pydantic models for messages, completions, responses and pagination, +plus message-normalization helpers. Most names are importable directly from +`dashscope.types`. + +## Messages & content parts + +::: dashscope.types.messages.Message + +::: dashscope.types.messages.TextPart + +::: dashscope.types.messages.ImagePart + +::: dashscope.types.messages.AudioPart + +::: dashscope.types.messages.VideoPart + +::: dashscope.types.messages.ToolCall + +::: dashscope.types.messages.ToolCallFunction + +## Completion models + +::: dashscope.types.completions.ChatCompletion + +::: dashscope.types.completions.ChatCompletionChunk + +::: dashscope.types.completions.ChatCompletionMessage + +::: dashscope.types.completions.Choice + +::: dashscope.types.completions.StreamChoice + +::: dashscope.types.completions.Delta + +::: dashscope.types.completions.SearchInfo + +::: dashscope.types.completions.SearchResult + +## Common & pagination + +::: dashscope.types.common.ResponseBase + +::: dashscope.types.common.Usage + +::: dashscope.types.common.JobStatus + +::: dashscope.types.pagination.BasePage + +## Helpers + +::: dashscope.types.messages.normalize_messages + +::: dashscope.types.messages.extract_text + +::: dashscope.types.completions.parse_completion + +::: dashscope.types.completions.parse_chunk \ No newline at end of file diff --git a/docs/en/release-notes.md b/docs/en/release-notes.md new file mode 100644 index 00000000..776a0aec --- /dev/null +++ b/docs/en/release-notes.md @@ -0,0 +1,45 @@ +--- +description: "Release notes and changelog pointers for the dashscope Python SDK, with 2.0 highlights." +--- +# Release Notes + +The authoritative, per-release changelog is published on +[GitHub Releases](https://github.com/dashscope/dashscope-sdk-python/releases). +This page summarizes the major lines and links to recent tags. +Current SDK version: **{{ sdk_version }}**. + +## Recent releases + +| Tag | Notes | +| --- | --- | +| [v2.1.0](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.1.0) | [See release page](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.1.0) | +| [v2.0.4](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.4) | [See release page](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.4) | +| [v2.0.3](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.3) | [See release page](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.3) | +| [v2.0.2](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.2) | [See release page](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.2) | +| [v2.0.1](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.1) | [See release page](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.1) | + +## 2.0 highlights + +Version 2.0 introduced the resource-style client modeled on the ergonomics +of the OpenAI SDK: + +- **Entry point** — `client.chat.completions.create(...)` instead of + module-level static classes; one-liner `dashscope.chat("qwen-plus", "...")`. +- **Responses** — typed objects (`resp.output_text`, `resp.usage.total_tokens`) + instead of raw dict-like results. +- **Errors** — typed `DashScopeError` exceptions raised by default. +- **Streaming** — `ChatStream` with `.text_stream`, `.reasoning_stream` and + `.get_final_message()`. +- **Protocols** — one client speaks `native`, `openai` or `anthropic` + via `protocol=`. +- **Async** — `dashscope.AsyncClient()` mirrors the sync surface. +- **Connections** — one keep-alive pool per client, shared across resources. +- **Configuration** — layered: arguments → `dashscope.settings` → environment + → `~/.dashscope/config.toml`. + +## 1.x line + +The 1.x API is preserved for backward compatibility under +`dashscope.legacy_1x` and remains importable from the `dashscope` root. +It is frozen: new capabilities land only in the 2.x surface. +See [Legacy 1.x](reference/legacy.md). \ No newline at end of file diff --git a/docs/hooks.py b/docs/hooks.py new file mode 100644 index 00000000..27f0a1b9 --- /dev/null +++ b/docs/hooks.py @@ -0,0 +1,28 @@ +"""MkDocs hooks: surface the SDK version from dashscope/version.py in pages. + +Pages opt in with the ``{{ sdk_version }}`` placeholder; the value is read +from the source of truth at build time so docs never drift from the package. +""" +import re +from pathlib import Path + + +def _read_version(docs_dir: str) -> str: + source = Path(docs_dir).parent / "dashscope" / "version.py" + match = re.search( + r'__version__\s*=\s*["\']([^"\']+)["\']', + source.read_text(encoding="utf-8"), + ) + return match.group(1) if match else "unknown" + + +def on_config(config): + config.extra["sdk_version"] = _read_version(config.docs_dir) + return config + + +def on_page_markdown(markdown, *, page, config, files): + return markdown.replace( + "{{ sdk_version }}", + config.extra.get("sdk_version", "unknown"), + ) \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 9534b018..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/overrides/main.html b/docs/overrides/main.html new file mode 100644 index 00000000..b4a0e920 --- /dev/null +++ b/docs/overrides/main.html @@ -0,0 +1,17 @@ +{% extends "base.html" %} + +{# Elastic-style per-page action block: view source, report, edit, contribute #} +{% block content %} + {{ super() }} + {% set zh = (i18n_page_locale | default("en")) == "zh" %} + +{% endblock %} \ No newline at end of file diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst deleted file mode 100644 index b9aade44..00000000 --- a/docs/source/_templates/autosummary/class.rst +++ /dev/null @@ -1,10 +0,0 @@ -.. currentmodule:: {{ module }} - - -{{ name | underline}} - -.. autoclass:: {{ name }} - :inherited-members: - :members: - -.. autogenerated from source/_templates/autosummary/class.rst diff --git a/docs/source/_templates/classtemplate.rst b/docs/source/_templates/classtemplate.rst deleted file mode 100644 index d3ea0e59..00000000 --- a/docs/source/_templates/classtemplate.rst +++ /dev/null @@ -1,12 +0,0 @@ -.. currentmodule:: {{ module }} - - -{{ name | underline}} - -.. autoclass:: {{ name }} - :members: - :special-members: __init__, __call__ - -.. - autogenerated from source/_templates/classtemplate.rst - note it does not have :inherited-members: diff --git a/docs/source/_templates/sobolengine.rst b/docs/source/_templates/sobolengine.rst deleted file mode 100644 index e732eecc..00000000 --- a/docs/source/_templates/sobolengine.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. currentmodule:: {{ module }} - - -{{ name | underline}} - -.. autoclass:: {{ name }} - :members: - :exclude-members: MAXBIT, MAXDIM - :undoc-members: - - -.. - autogenerated from source/_templates/sobolengine.rst - note it has specific options diff --git a/docs/source/api/dashscope.aigc.rst b/docs/source/api/dashscope.aigc.rst deleted file mode 100644 index 7af21a3f..00000000 --- a/docs/source/api/dashscope.aigc.rst +++ /dev/null @@ -1,15 +0,0 @@ -dashscope.legacy_1x.aigc -======================== - -.. automodule:: dashscope.legacy_1x.aigc - -.. currentmodule:: dashscope.legacy_1x.aigc - -.. autosummary:: - :toctree: generated - :nosignatures: - :template: classtemplate.rst - - conversation.HistoryItem - conversation.History - conversation.Conversation diff --git a/docs/source/api/generated/dashscope.aigc.conversation.Conversation.rst b/docs/source/api/generated/dashscope.aigc.conversation.Conversation.rst deleted file mode 100644 index b418068b..00000000 --- a/docs/source/api/generated/dashscope.aigc.conversation.Conversation.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. currentmodule:: dashscope.legacy_1x.aigc.conversation - - -Conversation -============ - -.. autoclass:: Conversation - :members: - :special-members: __init__, __call__ - -.. - autogenerated from source/_templates/classtemplate.rst - note it does not have :inherited-members: \ No newline at end of file diff --git a/docs/source/api/generated/dashscope.aigc.conversation.History.rst b/docs/source/api/generated/dashscope.aigc.conversation.History.rst deleted file mode 100644 index 819bb62e..00000000 --- a/docs/source/api/generated/dashscope.aigc.conversation.History.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. currentmodule:: dashscope.legacy_1x.aigc.conversation - - -History -======= - -.. autoclass:: History - :members: - :special-members: __init__, __call__ - -.. - autogenerated from source/_templates/classtemplate.rst - note it does not have :inherited-members: \ No newline at end of file diff --git a/docs/source/api/generated/dashscope.aigc.conversation.HistoryItem.rst b/docs/source/api/generated/dashscope.aigc.conversation.HistoryItem.rst deleted file mode 100644 index edfa7fb4..00000000 --- a/docs/source/api/generated/dashscope.aigc.conversation.HistoryItem.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. currentmodule:: dashscope.legacy_1x.aigc.conversation - - -HistoryItem -=========== - -.. autoclass:: HistoryItem - :members: - :special-members: __init__, __call__ - -.. - autogenerated from source/_templates/classtemplate.rst - note it does not have :inherited-members: \ No newline at end of file diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 4029bf41..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,145 +0,0 @@ -# -*- coding: utf-8 -*- -# Configuration file for the Sphinx documentation builder. -# -# This file only contains a selection of the most common options. For a full -# list see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -import os -import sys - -# import sphinx_book_theme - -sys.path.insert(0, os.path.abspath("../../")) -# -- Project information ----------------------------------------------------- - -project = "dashscope" -copyright = "2023-2024, Alibaba DashScope" -author = "dashscope Authors" -version_file = "../../dashscope/version.py" - - -def get_version(): - with open(version_file, "r", encoding="utf-8") as f: - exec(compile(f.read(), version_file, "exec")) - return locals()["__version__"] - - -# The full version, including alpha/beta/rc tags -version = get_version() -release = version - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.napoleon", - "sphinx.ext.autosummary", - "sphinx.ext.autodoc", - "sphinx.ext.viewcode", - "sphinx_markdown_tables", - "sphinx_copybutton", - "myst_parser", -] - -autodoc_mock_imports = [ - "matplotlib", - "pycocotools", - "terminaltables", -] -# build the templated autosummary files -autosummary_generate = True -numpydoc_show_class_members = False - -# Enable overriding of function signatures in the first line of the docstring. -autodoc_docstring_signature = True - -# Disable docstring inheritance -autodoc_inherit_docstrings = False - -# Show type hints in the description -autodoc_typehints = "description" - -# Add parameter types if the parameter is documented in the docstring -autodoc_typehints_description_target = "documented_params" - -autodoc_default_options = { - "member-order": "bysource", -} - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -source_suffix = [".rst", ".md"] - -# The master toctree document. -root_doc = "index" - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path. -exclude_patterns = [ - "build", - "source/.ipynb_checkpoints", - "source/api/generated", - "Thumbs.db", - ".DS_Store", -] -# A list of glob-style patterns [1] that are used to find source files. -# They are matched against the source file names relative to the source -# directory, using slashes as directory separators on all platforms. -# The default is **, meaning that all files are recursively included from -# the source directory. -# include_patterns = [ -# 'index.rst', -# 'quick_start.md', -# 'develop.md', -# 'faq.md', -# 'change_log.md', -# 'api/dashscope.hub*', -# 'api/dashscope.models.base*', -# 'api/dashscope.models.builder*', -# 'api/dashscope.pipelines.base*', -# 'api/dashscope.pipelines.builder*', -# 'api/dashscope.preprocessors.base*', -# 'api/dashscope.preprocessors.builder*', -# 'api/dashscope.trainers.base*', -# 'api/dashscope.trainers.builder*', -# ] -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -# html_theme = 'sphinx_book_theme' -# html_theme_path = [sphinx_book_theme.get_html_theme_path()] -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] -# html_css_files = ['css/readthedocs.css'] - -# -- Options for HTMLHelp output --------------------------------------------- -# Output file base name for HTML help builder. -# htmlhelp_basename = 'dashscope_doc' - -# -- Extension configuration ------------------------------------------------- -# Ignore >>> when copying code -copybutton_prompt_text = r">>> |\.\.\. " -copybutton_prompt_is_regexp = True - -# Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"https://docs.python.org/": None} diff --git a/docs/source/develop.md b/docs/source/develop.md deleted file mode 100644 index 45ddc7c6..00000000 --- a/docs/source/develop.md +++ /dev/null @@ -1,48 +0,0 @@ -# Develop - -## 1. Code Style -We adopt [PEP8](https://www.python.org/dev/peps/pep-0008/) as the preferred code style. - -We use the following toolsseed isortseed isortseed isort for linting and formatting: -- [flake8](http://flake8.pycqa.org/en/latest/): linter -- [yapf](https://github.com/google/yapf): formatter -- [isort](https://github.com/timothycrosley/isort): sort imports - -Style configurations of yapf and isort can be found in [setup.cfg](../../setup.cfg). -We use [pre-commit hook](https://pre-commit.com/) that checks and formats for `flake8`, `yapf`, `seed-isort-config`, `isort`, `trailing whitespaces`, -fixes `end-of-files`, sorts `requirments.txt` automatically on every commit. -The config for a pre-commit hook is stored in [.pre-commit-config](../../.pre-commit-config.yaml). -After you clone the repository, you will need to install initialize pre-commit hook. -```bash -pip install -r requirements-test.txt -``` -From the repository folder -```bash -pre-commit install -``` - -After this on every commit check code linters and formatter will be enforced. - -If you want to use pre-commit to check all the files, you can run -```bash -pre-commit run --all-files -``` - -If you only want to format and lint your code, you can run -```bash -make linter -``` - -## 2. Tests - -Run the current root implementation, archived compatibility suites, or the -complete suite with: - -```bash -python -m pytest tests --ignore=tests/legacy_1x -q -python -m pytest tests/legacy_1x -q -python -m pytest tests -q -``` - -Current coverage uses `coverage run -m pytest tests ---ignore=tests/legacy_1x`, followed by `coverage report -m`. diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 2a611958..00000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. dashscope sdk documentation file, - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -DashScope SDK DOCUMENTATION -======================== - -.. toctree:: - :maxdepth: 2 - :caption: DEVELOPER GUIDE - - develop.md - -.. toctree:: - :maxdepth: 2 - :caption: API Doc - - AIGC - - - -Indices and tables -================== -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css new file mode 100644 index 00000000..970c1997 --- /dev/null +++ b/docs/stylesheets/extra.css @@ -0,0 +1,43 @@ +/* FastAPI-style template tweaks on top of Material: + - white header keeps links readable (primary fg is white) + - active top tab gets an underline indicator + - page title centered, like fastapi.tiangolo.com */ +:root { + --md-typeset-a-color: #3f51b5; +} + +[data-md-color-scheme="slate"] { + --md-typeset-a-color: #8c9eff; +} + +.md-tabs__item--active { + border-bottom: 2px solid currentColor; +} + +.md-typeset h1 { + text-align: center; +} + +/* Elastic-style per-page action block (see overrides/main.html) */ +.docs-actions { + display: flex; + flex-direction: column; + gap: .4rem; + margin-top: 2rem; + padding-top: 1rem; + border-top: 1px solid var(--md-default-fg-color--lightest); + font-size: .7rem; +} + +.docs-actions a { + display: inline-flex; + align-items: center; + gap: .4rem; + color: var(--md-typeset-a-color); +} + +.docs-actions svg { + width: 1em; + height: 1em; + fill: currentColor; +} \ No newline at end of file diff --git a/docs/zh/about.md b/docs/zh/about.md new file mode 100644 index 00000000..c976464c --- /dev/null +++ b/docs/zh/about.md @@ -0,0 +1,42 @@ +--- +description: "关于 DashScope Python SDK:项目链接、Apache-2.0 许可证、兼容性与版本策略。" +--- +# 关于 + +## 项目 + +DashScope Python SDK(PyPI 包名 `dashscope`)是 +[阿里云百炼(Model Studio)](https://help.aliyun.com/zh/model-studio/) +的官方 Python 客户端,覆盖文本生成、多模态理解、向量嵌入、重排序、 +图像/视频生成、语音合成与识别、微调、智能体强化学习、托管智能体与应用调用。 + +- 源码:[github.com/dashscope/dashscope-sdk-python](https://github.com/dashscope/dashscope-sdk-python) +- 包:[pypi.org/project/dashscope](https://pypi.org/project/dashscope/) +- 服务文档:[百炼帮助中心](https://help.aliyun.com/zh/model-studio/) + +## 许可证 + +SDK 采用 +[Apache License 2.0](https://github.com/dashscope/dashscope-sdk-python/blob/main/LICENSE) +授权。第三方声明(如内置的 certifi CA 证书包)见 +[NOTICE](https://github.com/dashscope/dashscope-sdk-python/blob/main/NOTICE)。 + +## 兼容性与版本策略 + +- 2.x 是积极开发的主线:资源式 `Client` / `AsyncClient`、 + 类型化响应与异常。 +- 完整 1.x 公共接口仍可从历史路径导入,由 `dashscope.legacy_1x` 下 + 的冻结门面实现;不再新增能力。 +- AgentStudio 与 Agentic RL 是应用子 SDK,拥有独立的客户端、 + 返回与错误契约。 +- 需要 Python 3.9+;可选交互式助手(`dashscope[acli]`)需要 Python 3.10+。 +- 当前 SDK 版本:**{{ sdk_version }}** —— 见[发行说明](release-notes.md)。 + +## 获取帮助 + +- 在 [GitHub Issues](https://github.com/dashscope/dashscope-sdk-python/issues) + 反馈缺陷与需求。 +- 浏览 [API 参考](reference/client.md)或[快速开始](quickstart.md)。 +- 失败的调用可以自我解释:启用 devkit 诊断后, + `DashScopeError.diagnosis` 会给出结构化修复建议 + (见[开发工具](reference/devkit.md))。 \ No newline at end of file diff --git a/docs/zh/cli.md b/docs/zh/cli.md new file mode 100644 index 00000000..2d514bbb --- /dev/null +++ b/docs/zh/cli.md @@ -0,0 +1,76 @@ +--- +description: "dashscope 命令行:全局选项、退出码与全部命令组。" +--- +# 命令行工具(CLI) + +安装 SDK 时会同时安装 `dashscope` 命令(以及归档 1.x 命令树的 +`dashscope1`)。CLI 与 SDK 资源一一对应,`Client` 能做的事都可以 +用 shell 脚本完成。 + +```bash +dashscope version # 打印 SDK 版本(是子命令,不是 --version) +dashscope auth login # 保存 API Key(交互式输入) +dashscope chat create --model qwen-plus --prompt "你好!" +dashscope -k sk-xxx --output json ft list +``` + +## 全局选项 + +全局选项放在子命令**之前**: + +| 选项 | 含义 | +| --- | --- | +| `-k`, `--api-key` | DashScope API Key;覆盖环境变量与配置文件。 | +| `--protocol` | 传输协议:`native`、`openai` 或 `anthropic`。 | +| `--base-url` | 覆盖服务基础地址。 | +| `--workspace` | 业务空间 ID。 | +| `--region` | 服务地域,如 `cn-beijing`、`ap-southeast-1`。 | +| `--timeout` | 单次请求超时(秒)。 | +| `-o`, `--output` | 输出格式;机器格式保持 stdout 可解析(如 `json`)。 | + +错误以 `Error [category]: message` 输出到 stderr。退出码:`0` 成功, +`1` 服务端/限流/网络,`2` 命令行错误,`3` 鉴权,`4` 未找到。 + +## 命令组 + +| 命令组 | 用途 | +| --- | --- | +| `auth` | `login` / `whoami` / `logout` —— 管理已保存的 API Key。 | +| `config` | `set` / `get` / `list` —— CLI 持久化配置。 | +| `chat` | 对话补全(同步与流式)。 | +| `multimodal` | 多模态理解/生成调用。 | +| `embeddings` | 文本向量调用与批量任务。 | +| `rerank` | 文档重排序。 | +| `tokenization` | Token 计数。 | +| `images` | 图像生成任务。 | +| `videos` | 视频生成任务。 | +| `audio` | TTS / ASR / 实时语音命令。 | +| `files` | 文件上传、列表、查询与删除。 | +| `models` | 浏览模型目录。 | +| `ft` | 微调任务(`fine-tunes` 为隐藏别名)。 | +| `deployments` | 模型部署管理。 | +| `rl` | Agentic RL 数据集、函数与任务(别名 `agentic-rl`)。 | +| `apps` | 百炼应用补全。 | +| `tingwu` | 会议转写与分析。 | +| `decision` | 结构化决策/评判调用。 | +| `agentstudio` | AgentStudio 托管智能体资源。 | +| `oss` | 大体积媒体输入的 OSS 上传辅助。 | + +每个命令的具体参数请运行 `dashscope <命令组> --help` +(或 `dashscope <命令组> <命令> --help`)查看。 + +## 智能体入口 + +**不带任何参数**运行 `dashscope` 会启动交互式 AgenticX 智能体, +而不是命令树。需要可选 extra 与 Python 3.10+: + +```bash +pip install -U "dashscope[acli]" +dashscope # 启动智能体 +``` + +## 1.x CLI + +旧版命令树(`generation create`、`application create`、`files.upload`、 +`login` 等)单独安装为 `dashscope1`,已冻结。在 `dashscope` 下运行 +1.x 命令名只会打印迁移提示,指向 `dashscope1` 或对应的 2.0 命令。 \ No newline at end of file diff --git a/docs/zh/develop.md b/docs/zh/develop.md new file mode 100644 index 00000000..4d8d38ce --- /dev/null +++ b/docs/zh/develop.md @@ -0,0 +1,50 @@ +--- +description: "开发者指南:仓库结构、测试、docstring 规范与发布流程。" +--- +# 开发指南 + +## 1. 代码风格 +我们采用 [PEP8](https://www.python.org/dev/peps/pep-0008/) 作为首选代码风格。 + +使用以下工具进行静态检查与格式化: +- [flake8](http://flake8.pycqa.org/en/latest/):静态检查 +- [yapf](https://github.com/google/yapf):格式化 +- [isort](https://github.com/timothycrosley/isort):import 排序 + +yapf 与 isort 的风格配置见 [setup.cfg](https://github.com/dashscope/dashscope-sdk-python/blob/main/setup.cfg)。 +我们使用 [pre-commit 钩子](https://pre-commit.com/),在每次提交时自动执行 `flake8`、`yapf`、`seed-isort-config`、`isort`、 +`trailing whitespaces` 检查与格式化,修复 `end-of-files`,并对 `requirements.txt` 排序。 +pre-commit 钩子的配置保存在 [.pre-commit-config](https://github.com/dashscope/dashscope-sdk-python/blob/main/.pre-commit-config.yaml)。 +克隆仓库后,需要安装并初始化 pre-commit 钩子: +```bash +pip install -r requirements-test.txt +``` +在仓库目录下执行: +```bash +pre-commit install +``` + +此后每次提交都会强制执行代码检查与格式化。 + +如果想用 pre-commit 检查全部文件,可以运行: +```bash +pre-commit run --all-files +``` + +如果只想格式化并检查代码,可以运行: +```bash +make linter +``` + +## 2. 测试 + +分别运行当前主线实现、归档兼容套件或完整测试套件: + +```bash +python -m pytest tests --ignore=tests/legacy_1x -q +python -m pytest tests/legacy_1x -q +python -m pytest tests -q +``` + +当前覆盖率统计使用 `coverage run -m pytest tests +--ignore=tests/legacy_1x`,随后执行 `coverage report -m`。 \ No newline at end of file diff --git a/docs/zh/features.md b/docs/zh/features.md new file mode 100644 index 00000000..2b365977 --- /dev/null +++ b/docs/zh/features.md @@ -0,0 +1,93 @@ +--- +description: "dashscope 2.0 SDK 特征总览:类型化资源、同步/异步、协议、流式、错误、dev mock、CLI 与 1.x 兼容。" +--- +# 特征 + +dashscope 2.0 SDK 是面向阿里云百炼(Model Studio / DashScope)的 +类型化、资源式客户端。亮点如下: + +## 类型化资源客户端 + +- 一个 `Client()` 持有 keep-alive 连接池,供所有资源共享。 +- 能力以类型化命名空间挂在客户端上:`client.chat`、`client.images`、 + `client.audio`、`client.files`、`client.fine_tunes`…… +- 响应是类型化对象:直接读 `resp.output_text`、`resp.usage.total_tokens`, + 不再翻原始 dict。 +- 失败默认抛出类型化异常——无需手动检查 `status_code`。 + +见[客户端与配置](reference/client.md)。 + +## 同步与异步,同一套接口 + +- `dashscope.AsyncClient()` 逐方法镜像同步客户端。 +- 共享的分层配置:参数 → `dashscope.settings` → 环境变量 → + `~/.dashscope/config.toml`。 +- 例外:双工语音 WebSocket 会话仅支持同步。 + +## 一个客户端,三种协议 + +- 同一个 `client.chat.completions` 调用可使用 DashScope `native`、 + OpenAI 兼容或 Anthropic 兼容传输协议。 +- 通过 `Client(protocol="openai")`、`protocol` 配置项或 + `DASHSCOPE_PROTOCOL` 选择。 + +见[协议适配器](reference/protocols.md)。 + +## 像读文本一样的流式 + +- `ChatStream` 提供 `.text_stream`、`.reasoning_stream` 与 + `.get_final_message()`——迭代纯字符串,结束时拿到组装好的类型化消息。 +- SSE 传输,自动重试与重连处理。 + +见[对话(Chat)](reference/chat.md)。 + +## WebSocket 实时语音 + +- `client.audio` 下的语音合成(TTS)、识别(ASR)、omni 实时与 + Qwen Live 会话。 +- 音色与热词定制资源。 + +见[语音(Audio)](reference/audio.md)与 +[Qwen Live 指南](guides/qwen-live-python-sdk.md)。 + +## 类型化错误与自诊断 + +- `DashScopeError` 异常体系覆盖传输、校验、HTTP 状态与 WebSocket 失败, + 附带 `code`、`request_id` 与响应体。 +- 可选的本地诊断把失败转化为结构化双语修复建议,见 `error.diagnosis`。 + +见[错误(Errors)](reference/errors.md)与[开发工具](reference/devkit.md)。 + +## 用 dev mock 离线开发 + +- `static` / `replay` / `record` 三种模式走通完整 HTTP 请求路径, + 不消耗云端 token。 +- 关闭时零开销;成功路径上不导入任何相关代码。 + +见[开发工具](reference/devkit.md)。 + +## 托管智能体与智能体强化学习 + +- `dashscope.applications.agentstudio`:独立子 SDK,覆盖托管智能体、 + 会话、环境、部署、记忆、技能与密钥库。 +- `dashscope.applications.finetune.AgenticRL` 加装饰器, + 本地编写 rollout / reward 函数。 + +见 [AgentStudio](reference/agentstudio.md)与 +[强化学习微调](reference/agentic-rl.md)。 + +## 真正的命令行 + +- `dashscope` CLI 覆盖对话、语音、图像、文件、微调、部署、RL、应用等, + 全局选项一致,支持机器可读输出(`-o json`)。 +- 可选交互式 AI 助手:`pip install "dashscope[acli]"`。 + +见[命令行工具](cli.md)。 + +## 1.x 兼容,已冻结 + +- 完整 1.x 公共接口仍可从历史路径导入 + (`from dashscope import Generation`),由 `dashscope.legacy_1x` 下 + 的冻结门面实现。 + +见[旧版 1.x](reference/legacy.md)。 \ No newline at end of file diff --git a/docs/qwen-live-python-sdk.md b/docs/zh/guides/qwen-live-python-sdk.md similarity index 99% rename from docs/qwen-live-python-sdk.md rename to docs/zh/guides/qwen-live-python-sdk.md index b42966f2..7f37908c 100644 --- a/docs/qwen-live-python-sdk.md +++ b/docs/zh/guides/qwen-live-python-sdk.md @@ -1,3 +1,6 @@ +--- +description: "用 dashscope SDK 接入 Qwen Live WebSocket 实时语音会话的完整流程。" +--- # Qwen Live Python SDK Qwen Live 是面向实时语音交互的 WebSocket 模型:客户端持续上行音频,服务端返回音频、转写与用量等事件。接口位于 `client.audio.live`,提供连接管理、会话配置、音频上行、委派回注与事件迭代。 diff --git a/docs/zh/guides/recipes.md b/docs/zh/guides/recipes.md new file mode 100644 index 00000000..f8fad369 --- /dev/null +++ b/docs/zh/guides/recipes.md @@ -0,0 +1,123 @@ +--- +description: "dashscope 2.0 各能力的即抄即用示例:多模态、图像、视频、向量、重排序、语音、应用、文件与模型。" +--- +# 能力速查示例 + +每个能力一段可直接运行的短示例。均假设已导出 `DASHSCOPE_API_KEY` +(见[快速开始](../quickstart.md)),并使用同步客户端;`AsyncClient` +以 `await` 镜像全部调用。响应字段均为类型化对象, +[API 参考](../reference/client.md)逐一说明。 + +## 多模态理解 + +```python +from dashscope import Client + +with Client() as client: + resp = client.multimodal.chat.create( + model="qwen-vl-plus", + messages=[{ + "role": "user", + "content": [ + {"image": "https://example.com/dog_and_girl.jpeg"}, + {"text": "这张图里有什么?"}, + ], + }], + ) + print(resp.output_text) +``` + +## 图像生成 + +`generate()` 提交任务并等待完成;完成后的 job 携带结果 URL。 + +```python +job = client.images.generate( + model="wan2.2-t2i-flash", + prompt="一只漂浮在太空中的猫宇航员", +) +print(job.image_urls) +``` + +## 视频生成 + +```python +job = client.videos.generate( + model="wan2.2-t2v-plus", + prompt="一只漂浮在太空中的猫宇航员", +) +print(job.video_url) +``` + +## 文本向量 + +```python +resp = client.embeddings.create( + model="text-embedding-v4", + input=["hello world", "你好世界"], +) +print(len(resp.embeddings[0].embedding)) +``` + +## 重排序 + +```python +resp = client.rerank.create( + model="gte-rerank-v2", + query="什么是 DashScope?", + documents=["DashScope 是模型服务。", "今天天气不错。"], + top_n=2, +) +print(resp.results) +``` + +## 语音合成 + +`synthesize()` 返回拼接后的音频字节。 + +```python +audio = client.audio.tts.synthesize( + "你好,DashScope", + model="cosyvoice-v2", + voice="longxiaochun", +) +with open("out.mp3", "wb") as f: + f.write(audio) +``` + +## 文件识别 + +```python +for event in client.audio.asr.recognize_file( + "audio.pcm", + model="paraformer-realtime-v2", +): + print(event) +``` + +实时会话见[语音](../reference/audio.md)与 +[Qwen Live 指南](qwen-live-python-sdk.md)。 + +## 应用调用 + +```python +resp = client.apps.create(app_id="your-app-id", prompt="介绍一下你自己") +print(resp.text) +``` + +## 文件上传 + +```python +file = client.files.upload(file_path="train.jsonl", purpose="fine-tune") +print(file.id) +``` + +## 模型列表 + +```python +page = client.models.list() +print(len(page.items), "个可用模型") +``` + +完整资源接口(含批量任务与微调)见 +[客户端资源](../reference/resources.md)。 \ No newline at end of file diff --git a/docs/zh/index.md b/docs/zh/index.md new file mode 100644 index 00000000..1e3e5aad --- /dev/null +++ b/docs/zh/index.md @@ -0,0 +1,141 @@ +--- +description: "阿里云百炼(DashScope)官方 Python SDK:类型化同步/异步客户端、示例与特征总览。" +--- +# DashScope Python SDK + +`dashscope` SDK 是 +[阿里云百炼(Model Studio)](https://help.aliyun.com/zh/model-studio/) +的官方 Python 客户端:对话补全、多模态理解、向量嵌入、重排序、 +图像与视频生成、语音合成与识别、实时语音、微调、智能体强化学习、 +托管智能体与应用调用。 + +2.0 是类型化、资源式客户端——`dashscope.Client()`——参照 OpenAI SDK +的人体工学:一个客户端持有共享连接池,每种能力以类型化资源挂在 +其上,响应是类型化对象,失败默认抛出异常。 + +!!! tip "从哪里开始" + 初次使用?跟随[快速开始](quickstart.md)。迁移既有 1.x 代码? + 见[从 1.x 迁移](migration.md)。 + +## 特征 + +- **类型化资源** —— `client.chat`、`client.images`、`client.audio`…… +- **同步与异步** —— `AsyncClient` 镜像同步接口。 +- **三种协议** —— 一个客户端支持 `native`、`openai`、`anthropic`。 +- **像读文本一样的流式** —— `.text_stream`、`.reasoning_stream`。 +- **类型化错误 + 自诊断**,以及离线 **dev mock**。 +- **真正的命令行**与可选交互式 AI 助手。 + +完整列表见[特征](features.md)。 + +## 要求 + +- Python 3.9+(可选交互式助手需要 3.10+)。 +- 百炼 API Key——在[百炼控制台](https://bailian.console.aliyun.com/) + 创建后导出: + +```shell +export DASHSCOPE_API_KEY="sk-..." +``` + +## 安装 + +```shell +pip install -U dashscope +``` + +基础安装覆盖 SDK API 调用、`dashscope` CLI、Agentic RL 微调与本地 +分词器。可选 extras 用于配置交互式 AI 助手,例如 +`pip install "dashscope[acli]"`(见[命令行工具](cli.md))。 + +## 例子 + +### 创建它 + +```python +import dashscope + +client = dashscope.Client() # 读取 DASHSCOPE_API_KEY +``` + +### 运行它 + +```python +resp = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "讲个笑话"}], +) +print(resp.output_text) +print(resp.usage.total_tokens) +``` + +或一行式:`dashscope.chat("qwen-plus", "讲个笑话")`。 + +### 流式运行它 + +```python +with client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "写一首关于海的俳句"}], + stream=True, +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + final = stream.get_final_message() +``` + +### 异步运行它 + +```python +import asyncio +import dashscope + +async def main(): + async with dashscope.AsyncClient() as client: + resp = await client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "你好!"}], + ) + print(resp.output_text) + +asyncio.run(main()) +``` + +### 和它对话(实时语音) + +`client.audio.live` 通过 WebSocket 运行全双工语音会话——完整接入 +流程见 [Qwen Live 指南](guides/qwen-live-python-sdk.md)。 + +## 协议 + +同一个调用可以使用三种传输协议: + +```python +client = dashscope.Client(protocol="openai") # 或 "native"、"anthropic" +``` + +见[协议适配器](reference/protocols.md)。 + +## 错误与诊断 + +失败抛出类型化 `DashScopeError` 子类,携带 `code`、`request_id` 与 +响应体;可选的本地诊断在 `error.diagnosis` 上附加结构化修复建议。 +见[错误(Errors)](reference/errors.md)与[开发工具](reference/devkit.md)。 + +## 旧版 1.x + +完整 1.x 接口仍可从历史导入路径使用 +(`from dashscope import Generation`),由冻结门面实现。 +见[旧版 1.x](reference/legacy.md)。 + +## 依赖关系 + +基础安装引入 `requests`、`aiohttp`、`httpx` + `httpx-sse`、 +`websocket-client`、`pydantic`(v2)、`tenacity`、`tiktoken`,以及 +CLI 所需的 `typer` + `rich`。可选助手 extras 见上文「安装」一节。 + +## 执照 + +本项目采用 +[Apache License 2.0](https://github.com/dashscope/dashscope-sdk-python/blob/main/LICENSE) +授权。 \ No newline at end of file diff --git a/docs/zh/migration.md b/docs/zh/migration.md new file mode 100644 index 00000000..20502e72 --- /dev/null +++ b/docs/zh/migration.md @@ -0,0 +1,86 @@ +--- +description: "逐项对照 1.x 与 2.0,把既有代码迁移到资源式 dashscope 客户端。" +--- +# 从 1.x 迁移 + +2.0 客户端取代了 1.x 的模块级静态类,但完整 1.x 接口仍可从历史导入 +路径继续使用。可以按自己的节奏迁移——本页把旧习惯映射到新写法。 + +## 逐项对照 + +| | 1.x | 2.0 | +|---|---|---| +| 入口 | 模块级静态类:`Generation.call(...)` | 资源式客户端:`client.chat.completions.create(...)` | +| 一行式 | — | `dashscope.chat("qwen-plus", "讲个笑话")` | +| 响应 | 原始 dict 式;手动检查 `status_code == HTTPStatus.OK` | 类型化对象;读 `resp.output_text`、`resp.usage.total_tokens` | +| 错误 | 手动查看 `resp.code` / `resp.message` | 默认抛出类型化 `DashScopeError` 异常 | +| 流式 | 原始帧生成器 | `ChatStream` 提供 `.text_stream`、`.reasoning_stream`、`.get_final_message()` | +| 协议 | DashScope 原生 + 独立的兼容模式入口 | 一个客户端通过 `protocol=` 使用 `native`、`openai` 或 `anthropic` | +| 异步 | 独立的 `Aio*` 类 | `dashscope.AsyncClient()` 镜像同步接口 | +| 连接 | 每次调用新建会话 | 每客户端一个 keep-alive 连接池,跨资源共享 | +| 配置 | 模块全局变量(`dashscope.api_key`、`set_region`) | 分层:参数 → `dashscope.settings` → 环境变量 → `~/.dashscope/config.toml` | + +## 调用映射 + +| 1.x 类 | 2.0 资源 | +| --- | --- | +| `Generation` / `AioGeneration` | `client.chat.completions` | +| `MultiModalConversation` | `client.multimodal` | +| `ImageSynthesis` / `ImageGeneration` | `client.images` | +| `VideoSynthesis` | `client.videos` | +| `TextEmbedding` / `BatchTextEmbedding` | `client.embeddings` | +| `MultiModalEmbedding` | `client.multimodal`(embeddings) | +| `TextReRank` | `client.rerank` | +| `SpeechSynthesizer`(tts / tts_v2) | `client.audio.tts` | +| `Recognition` / `Transcription` | `client.audio.asr` | +| `Files` | `client.files` | +| `Models` | `client.models` | +| `FineTunes` | `client.fine_tunes` | +| `Deployments` | `client.deployments` | +| `Application` | `client.apps` | + +所有 1.x 类仍完整记录在[旧版 1.x](reference/legacy.md) 下。 + +## 迁移前后 + +1.x —— 调用后手动检查状态: + +```python +from http import HTTPStatus +from dashscope import Generation + +resp = Generation.call( + model="qwen-plus", + messages=[{"role": "user", "content": "你好!"}], +) +if resp.status_code != HTTPStatus.OK: + print(resp.code, resp.message) +else: + print(resp.output.text) +``` + +2.0 —— 类型化响应,失败抛异常: + +```python +from dashscope import Client, DashScopeError + +try: + with Client() as client: + resp = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "你好!"}], + ) + print(resp.output_text) +except DashScopeError as exc: + print(exc.code, exc.message) +``` + +## 保持不变的部分 + +- 导入路径:`from dashscope import Generation` 仍可用(冻结门面)。 +- `DASHSCOPE_API_KEY` 环境变量与控制台签发的密钥。 +- 模型名与请求体——native 协议下线上契约不变。 + +!!! tip "渐进迁移" + 两套接口可在同一进程中共存。逐个迁移调用点即可,没有统一的 + 切换截止日。各 2.x 版本的变更见[发行说明](release-notes.md)。 \ No newline at end of file diff --git a/docs/zh/quickstart.md b/docs/zh/quickstart.md new file mode 100644 index 00000000..6a378450 --- /dev/null +++ b/docs/zh/quickstart.md @@ -0,0 +1,142 @@ +--- +description: "安装 dashscope、配置 API Key,几分钟内完成第一次对话补全。" +--- +# 快速开始 + +dashscope 2.0 API 以带类型标注的 [Client](reference/client.md)(及其异步版本 +`AsyncClient`)为核心,通过 `client.chat`、`client.images`、`client.audio` +等资源命名空间组织各能力。本页带你从安装走到第一次对话补全。 + +## 安装 + +需要 Python 3.9 及以上版本。 + +```bash +python -m pip install -U dashscope +``` + +## 配置 API Key + +推荐通过环境变量 `DASHSCOPE_API_KEY` 提供密钥——不要把密钥硬编码进源码: + +```bash +export DASHSCOPE_API_KEY="" +``` + +也可以调用 `dashscope.save_api_key("sk-xxx")` 持久化保存密钥 +(写入 `~/.dashscope/api_key`),或在运行时通过 `dashscope.settings.api_key` +赋值。 + +配置按以下顺序解析,先命中者生效: + +1. `Client(...)` 显式参数 +2. 进程级 `dashscope.settings` +3. 环境变量(`DASHSCOPE_API_KEY`、`DASHSCOPE_BASE_URL` 等) +4. `config.toml` +5. API Key 文件 + +!!! tip "CI 与容器" + 在 CI 中把 `DASHSCOPE_API_KEY` 作为秘密环境变量注入; + `save_api_key` 仅适用于交互式本地机器。 + +## 一行调用对话 + +脚本和 notebook 场景下,`dashscope.chat` 会自动管理客户端: + +```python +import dashscope + +resp = dashscope.chat("qwen-plus", "讲个笑话") +print(resp.output_text) +``` + +额外的关键字参数会透传给 `client.chat.completions.create`。 + +## 使用 Client + +```python +import dashscope + +client = dashscope.Client() # 读取 DASHSCOPE_API_KEY +resp = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "你好!"}], +) +print(resp.output_text) +``` + +`Client` 持有 HTTP 连接池,用完后请关闭,或使用上下文管理器: + +```python +with dashscope.Client() as client: + resp = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "你好!"}], + ) +``` + +### 流式输出 + +传入 `stream=True` 并迭代增量块: + +```python +with dashscope.Client() as client: + stream = client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "写一首关于大海的俳句。"}], + stream=True, + ) + for chunk in stream: + if chunk.choices: + print(chunk.choices[0].delta.content or "", end="", flush=True) +``` + +### 异步调用 + +```python +import asyncio +import dashscope + + +async def main(): + async with dashscope.AsyncClient() as client: + resp = await client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "你好!"}], + ) + print(resp.output_text) + + +asyncio.run(main()) +``` + +## 错误处理 + +2.0 的所有失败都会抛出 [DashScopeError][dashscope.errors.DashScopeError] 的子类, +携带 `code`、`status_code`、`request_id` 和响应 `body`: + +```python +from dashscope import Client, DashScopeError + +try: + with Client() as client: + client.chat.completions.create( + model="qwen-plus", + messages=[{"role": "user", "content": "你好"}], + ) +except DashScopeError as exc: + print(exc.code, exc.status_code, exc.request_id, exc.message) +``` + +完整的异常层级(限流、鉴权、超时、WebSocket 错误等)见 [错误(Errors)](reference/errors.md)。 + +## 下一步 + +- [客户端与配置](reference/client.md) —— `Client` / `AsyncClient` 构造参数、 + `Config` / `Settings`、地域切换。 +- [对话(Chat)](reference/chat.md) —— 对话补全、流式输出与响应模型。 +- [语音(Audio)](reference/audio.md) —— TTS、ASR、实时与 Qwen Live 会话;完整接入流程见 + [Qwen Live 指南](guides/qwen-live-python-sdk.md)。 +- [资源(Resources)](reference/resources.md) —— 向量嵌入、重排序、图像、视频、文件、模型、 + 微调、部署、应用等。 +- [类型(Types)](reference/types.md) —— 共享的消息 / 响应 / 分页模型。 \ No newline at end of file diff --git a/docs/zh/reference/agentic-rl.md b/docs/zh/reference/agentic-rl.md new file mode 100644 index 00000000..5e8054a2 --- /dev/null +++ b/docs/zh/reference/agentic-rl.md @@ -0,0 +1,56 @@ +--- +description: "Agentic RL 微调 API 参考:提交入口与 reward/rollout 编写 API。" +--- +# 智能体强化学习微调(Agentic RL) + +`dashscope.applications.finetune` 承载 Agentic RL 微调流程: +用你自己编写的 rollout / reward 函数提交训练任务。服务端的任务、 +数据集与函数管理在 `client.rl` 下(见 +[资源](resources.md#reinforcement-learning));本页覆盖本地提交入口 +与 reward / rollout 组件的编写 API。 + +## 提交入口 + +::: dashscope.applications.finetune.agentic_rl.AgenticRL + +::: dashscope.applications.finetune.agentic_rl.SubmitOutput + +::: dashscope.applications.finetune.agentic_rl.SubmitResult + +## 函数装饰器 + +把普通 Python 函数注册为 rollout / reward 组件: + +::: dashscope.applications.finetune.reinforcement.component.reward_func + +::: dashscope.applications.finetune.reinforcement.component.sub_reward_func + +::: dashscope.applications.finetune.reinforcement.component.aggregate_func + +## 数据模型 + +::: dashscope.applications.finetune.reinforcement.component.RolloutInput + +::: dashscope.applications.finetune.reinforcement.component.RolloutOutput + +::: dashscope.applications.finetune.reinforcement.component.RewardInput + +::: dashscope.applications.finetune.reinforcement.component.Reward + +::: dashscope.applications.finetune.reinforcement.component.RewardOutput + +::: dashscope.applications.finetune.reinforcement.component.AgentOutput + +::: dashscope.applications.finetune.reinforcement.component.Task + +::: dashscope.applications.finetune.reinforcement.component.TaskStatus + +## 处理器基类与示例 + +::: dashscope.applications.finetune.reinforcement.component.AbstractRolloutProcessor + +::: dashscope.applications.finetune.reinforcement.component.AbstractRewardProcessor + +::: dashscope.applications.finetune.reinforcement.component.DemoRolloutProcessor + +::: dashscope.applications.finetune.reinforcement.component.DemoRewardProcessor \ No newline at end of file diff --git a/docs/zh/reference/agentstudio.md b/docs/zh/reference/agentstudio.md new file mode 100644 index 00000000..30a5a74a --- /dev/null +++ b/docs/zh/reference/agentstudio.md @@ -0,0 +1,242 @@ +--- +description: "AgentStudio 子 SDK API 参考:托管智能体、会话、部署、记忆与密钥库。" +--- +# AgentStudio(托管智能体) + +`dashscope.applications.agentstudio` 是 AgentStudio 托管智能体 API 的 +子 SDK:智能体、会话、事件、环境、部署、记忆、技能、密钥库、 +安全与 Webhook。所有资源都通过它自己的客户端访问: + +```python +from dashscope.applications.agentstudio import Client +from dashscope.applications.agentstudio import user_message + +client = Client(api_key="sk-xxx") +agent = client.agents.create(name="demo", model="qwen-plus") +session = client.sessions.create(agent=agent.id) +client.sessions.events.send(session.id, [user_message("你好!")]) +with client.sessions.events.stream(session.id) as stream: + for event in stream: + print(event.type) + if event.type == "session_status": + break +``` + +每个资源类都有异步孪生类(`AsyncAgents`、`AsyncSessions`……), +通过 `AsyncClient` 以相同方式使用。 + +## 客户端 + +::: dashscope.applications.agentstudio.Client + +::: dashscope.applications.agentstudio.AsyncClient + +## 智能体与会话 + +::: dashscope.applications.agentstudio.resources.agents.Agents + +::: dashscope.applications.agentstudio.resources.agents.AsyncAgents + +::: dashscope.applications.agentstudio.resources.sessions.Sessions + +::: dashscope.applications.agentstudio.resources.sessions.AsyncSessions + +::: dashscope.applications.agentstudio.resources.session_events.SessionEvents + +::: dashscope.applications.agentstudio.resources.session_events.AsyncSessionEvents + +::: dashscope.applications.agentstudio.resources.session_threads.SessionThreads + +::: dashscope.applications.agentstudio.resources.session_threads.AsyncSessionThreads + +::: dashscope.applications.agentstudio.resources.session_threads.SessionThreadEvents + +::: dashscope.applications.agentstudio.resources.session_threads.AsyncSessionThreadEvents + +::: dashscope.applications.agentstudio.resources.session_resources.SessionResources + +::: dashscope.applications.agentstudio.resources.session_resources.AsyncSessionResources + +## 环境与部署 + +::: dashscope.applications.agentstudio.resources.environments.Environments + +::: dashscope.applications.agentstudio.resources.environments.AsyncEnvironments + +::: dashscope.applications.agentstudio.resources.deployments.Deployments + +::: dashscope.applications.agentstudio.resources.deployments.AsyncDeployments + +::: dashscope.applications.agentstudio.resources.deployments.DeploymentRuns + +::: dashscope.applications.agentstudio.resources.deployments.AsyncDeploymentRuns + +## 文件 + +::: dashscope.applications.agentstudio.resources.files.Files + +::: dashscope.applications.agentstudio.resources.files.AsyncFiles + +## 记忆 + +::: dashscope.applications.agentstudio.resources.memory_stores.MemoryStores + +::: dashscope.applications.agentstudio.resources.memory_stores.AsyncMemoryStores + +::: dashscope.applications.agentstudio.resources.memory_stores.Memories + +::: dashscope.applications.agentstudio.resources.memory_stores.AsyncMemories + +::: dashscope.applications.agentstudio.resources.memory_stores.MemoryVersions + +::: dashscope.applications.agentstudio.resources.memory_stores.AsyncMemoryVersions + +## 技能 + +::: dashscope.applications.agentstudio.resources.skills.Skills + +::: dashscope.applications.agentstudio.resources.skills.AsyncSkills + +::: dashscope.applications.agentstudio.resources.skills.SkillVersions + +::: dashscope.applications.agentstudio.resources.skills.AsyncSkillVersions + +## 密钥库与凭证 + +::: dashscope.applications.agentstudio.resources.vaults.Vaults + +::: dashscope.applications.agentstudio.resources.vaults.AsyncVaults + +::: dashscope.applications.agentstudio.resources.vaults.Credentials + +::: dashscope.applications.agentstudio.resources.vaults.AsyncCredentials + +## 安全与 Webhook + +::: dashscope.applications.agentstudio.resources.security.Security + +::: dashscope.applications.agentstudio.resources.security.AsyncSecurity + +::: dashscope.applications.agentstudio.resources.webhook_endpoints.WebhookEndpoints + +::: dashscope.applications.agentstudio.resources.webhook_endpoints.AsyncWebhookEndpoints + +## 客户端事件辅助函数 + +::: dashscope.applications.agentstudio.user_message + +::: dashscope.applications.agentstudio.user_interrupt + +::: dashscope.applications.agentstudio.user_tool_result + +::: dashscope.applications.agentstudio.user_custom_tool_result + +::: dashscope.applications.agentstudio.user_tool_approval_response + +::: dashscope.applications.agentstudio.user_define_outcome + +## 核心类型 + +::: dashscope.applications.agentstudio.Message + +::: dashscope.applications.agentstudio.ServerEvent + +::: dashscope.applications.agentstudio.SessionResource + +::: dashscope.applications.agentstudio.StopReason + +::: dashscope.applications.agentstudio.Memory + +::: dashscope.applications.agentstudio.MemoryStore + +::: dashscope.applications.agentstudio.MemoryVersion + +::: dashscope.applications.agentstudio.PermissionPolicy + +::: dashscope.applications.agentstudio.SecurityAlert + +::: dashscope.applications.agentstudio.SecurityAlertList + +::: dashscope.applications.agentstudio.SecurityOverview + +## 请求参数类型 + +::: dashscope.applications.agentstudio.AgentCreateParams + +::: dashscope.applications.agentstudio.AgentUpdateParams + +::: dashscope.applications.agentstudio.SessionCreateParams + +::: dashscope.applications.agentstudio.SessionUpdateParams + +::: dashscope.applications.agentstudio.SessionEventSendParams + +::: dashscope.applications.agentstudio.EnvironmentCreateParams + +::: dashscope.applications.agentstudio.EnvironmentUpdateParams + +::: dashscope.applications.agentstudio.DeploymentCreateParams + +::: dashscope.applications.agentstudio.DeploymentUpdateParams + +::: dashscope.applications.agentstudio.WebhookEndpointCreateParams + +::: dashscope.applications.agentstudio.WebhookEndpointUpdateParams + +::: dashscope.applications.agentstudio.WebhookEventListParams + +## 常量与枚举 + +::: dashscope.applications.agentstudio.SessionStatus + +::: dashscope.applications.agentstudio.SSEEventType + +::: dashscope.applications.agentstudio.StopReasonType + +::: dashscope.applications.agentstudio.PermissionPolicyType + +::: dashscope.applications.agentstudio.WebhookStatus + +::: dashscope.applications.agentstudio.WebhookEventType + +::: dashscope.applications.agentstudio.WebhookDeliveryStatus + +::: dashscope.applications.agentstudio.WebhookDisabledReason + +## 分页、传输与异常 + +::: dashscope.applications.agentstudio.CursorPage + +::: dashscope.applications.agentstudio.AsyncCursorPage + +::: dashscope.applications.agentstudio.RequestOptions + +::: dashscope.applications.agentstudio.APIResponse + +::: dashscope.applications.agentstudio.AgentStudioError + +::: dashscope.applications.agentstudio.APIConnectionError + +::: dashscope.applications.agentstudio.APITimeoutError + +::: dashscope.applications.agentstudio.APIStatusError + +::: dashscope.applications.agentstudio.AuthenticationError + +::: dashscope.applications.agentstudio.PermissionDeniedError + +::: dashscope.applications.agentstudio.NotFoundError + +::: dashscope.applications.agentstudio.ConflictError + +::: dashscope.applications.agentstudio.InvalidRequestError + +::: dashscope.applications.agentstudio.RateLimitError + +::: dashscope.applications.agentstudio.OverloadedError + +::: dashscope.applications.agentstudio.InternalServerError + +::: dashscope.applications.agentstudio.StreamError + +::: dashscope.applications.agentstudio.StreamClosedError \ No newline at end of file diff --git a/docs/zh/reference/audio.md b/docs/zh/reference/audio.md new file mode 100644 index 00000000..415b17a8 --- /dev/null +++ b/docs/zh/reference/audio.md @@ -0,0 +1,82 @@ +--- +description: "语音合成、识别、实时会话与音色定制 API 参考。" +--- +# 语音(Audio) + +`client.audio` 汇集语音合成(TTS)、语音识别(ASR)、实时 WebSocket +会话与 Qwen Live,以及音色/热词定制能力。 + +## Audio 入口 + +::: dashscope.resources.audio.Audio + +::: dashscope.resources.audio.AsyncAudio + +## 语音合成(TTS) + +::: dashscope.resources.audio.tts.Tts + +::: dashscope.resources.audio.tts.SynthesisSession + +::: dashscope.resources.audio.http_tts.HttpTts + +::: dashscope.resources.audio.http_tts.AsyncHttpTts + +::: dashscope.resources.audio.http_tts.HttpSynthesis + +::: dashscope.resources.audio.http_tts.HttpSynthesisChunk + +::: dashscope.resources.audio.http_tts.HttpSynthesisStream + +## 语音识别(ASR) + +::: dashscope.resources.audio.asr.Asr + +::: dashscope.resources.audio.asr.AsyncAsr + +::: dashscope.resources.audio.asr.Recognition + +::: dashscope.resources.audio.asr.TranscriptionJobs + +::: dashscope.resources.audio.asr.AsyncTranscriptionJobs + +::: dashscope.resources.audio.asr.RecognitionResult + +## 实时与 Qwen Live + +`client.audio.live` 的完整接入流程参见 +[Qwen Live 指南](../guides/qwen-live-python-sdk.md)。 + +::: dashscope.resources.audio.realtime.Realtime + +::: dashscope.resources.audio.realtime.RealtimeSession + +::: dashscope.resources.audio.live.Live + +::: dashscope.resources.audio.live.LiveSession + +## 音色与热词定制 + +::: dashscope.resources.audio.customization.Voices + +::: dashscope.resources.audio.customization.Voice + +::: dashscope.resources.audio.customization.VoiceList + +::: dashscope.resources.audio.customization.VoiceDesign + +::: dashscope.resources.audio.customization.DesignedVoice + +::: dashscope.resources.audio.customization.DesignedVoiceList + +::: dashscope.resources.audio.customization.Vocabularies + +::: dashscope.resources.audio.customization.Vocabulary + +::: dashscope.resources.audio.customization.VocabularyList + +::: dashscope.resources.audio.phrases.Phrases + +::: dashscope.resources.audio.phrases.Phrase + +::: dashscope.resources.audio.phrases.PhraseList \ No newline at end of file diff --git a/docs/zh/reference/chat.md b/docs/zh/reference/chat.md new file mode 100644 index 00000000..10103e34 --- /dev/null +++ b/docs/zh/reference/chat.md @@ -0,0 +1,27 @@ +--- +description: "对话补全 API 参考:同步/异步资源与流式类。" +--- +# 对话(Chat) + +`client.chat.completions` 用于创建对话补全,支持流式与非流式。 +响应模型见[类型(Types)](types.md)。 + +## 资源类 + +::: dashscope.resources.chat.Chat + +::: dashscope.resources.chat.AsyncChat + +::: dashscope.resources.chat.completions.Completions + +::: dashscope.resources.chat.completions.AsyncCompletions + +::: dashscope.resources.chat.completions.ChatStream + +::: dashscope.resources.chat.completions.AsyncChatStream + +## 另请参阅 + +- [ChatCompletion][dashscope.types.completions.ChatCompletion] / + [ChatCompletionChunk][dashscope.types.completions.ChatCompletionChunk] —— 响应模型。 +- [类型(Types)](types.md) —— 消息、选项、增量与用量。 \ No newline at end of file diff --git a/docs/zh/reference/client.md b/docs/zh/reference/client.md new file mode 100644 index 00000000..c933027e --- /dev/null +++ b/docs/zh/reference/client.md @@ -0,0 +1,39 @@ +--- +description: "dashscope Client、AsyncClient、Config、Settings 与模块级辅助函数 API 参考。" +--- +# 客户端与配置 + +2.0 入口:`Client`(同步)与 `AsyncClient`(异步),以及配置和模块级辅助函数。 + +!!! note "异步范围" + `AsyncClient` 镜像同步接口,但双工语音 WebSocket 会话 + 除外——它们仅支持同步。 + +## 客户端 + +::: dashscope.client.Client + +::: dashscope.client.AsyncClient + +## 配置 + +::: dashscope._config.Config + +::: dashscope._config.Settings + +## 模块级辅助函数 + +::: dashscope.chat + +::: dashscope.set_region + +::: dashscope.save_api_key + +## WebSocket 传输 + +从包根导出的底层 WebSocket 原语,供实时语音会话使用, +也可用于自定义推理任务: + +::: dashscope.transport.ws_connection.WsConnection + +::: dashscope.transport.ws_connection.WsTask diff --git a/docs/zh/reference/devkit.md b/docs/zh/reference/devkit.md new file mode 100644 index 00000000..3b832665 --- /dev/null +++ b/docs/zh/reference/devkit.md @@ -0,0 +1,43 @@ +--- +description: "dev mock 模式与本地自诊断 API 参考。" +--- +# 开发工具(Devkit:Mock 与诊断) + +`dashscope.devkit` 提供两个可选的开发辅助能力,关闭时几乎零开销, +生产成功路径上不会导入本包。 + +- **Dev mock** —— `static` / `replay` / `record` 三种模式,不消耗云端 + token 即可走通完整的 2.0 HTTP 请求路径。仅覆盖 HTTP,不覆盖 + WebSocket 传输。代码中用 `dashscope.enable_dev_mock(...)` 启用, + 或设置 `DASHSCOPE_DEV_MOCK=`。 +- **自诊断** —— 本地双语规则表,把失败调用转化为结构化的修复建议, + 通过 `DashScopeError.diagnosis` 呈现。 + +根模块转发了 mock 开关:`dashscope.enable_dev_mock`、 +`dashscope.disable_dev_mock`、`dashscope.dev_mock_active`。 + +!!! tip "共享录制文件" + `record` 模式会把真实响应写盘;共享 fixture 前先用 + `set_redactor` 注册脱敏器。 + +## Dev mock 开关 + +::: dashscope.devkit.enable_dev_mock + +::: dashscope.devkit.disable_dev_mock + +::: dashscope.devkit.is_active + +::: dashscope.devkit.mock.DevMockMiss + +::: dashscope.devkit.mock.set_redactor + +## 自诊断 + +::: dashscope.devkit.diagnosis.Diagnosis + +::: dashscope.devkit.diagnosis.diagnose + +::: dashscope.devkit.diagnosis.render + +::: dashscope.devkit.diagnosis.install_excepthook \ No newline at end of file diff --git a/docs/zh/reference/errors.md b/docs/zh/reference/errors.md new file mode 100644 index 00000000..20ca5b82 --- /dev/null +++ b/docs/zh/reference/errors.md @@ -0,0 +1,58 @@ +--- +description: "DashScopeError 异常层级与错误码 API 参考。" +--- +# 错误(Errors) + +2.0 的所有异常都继承自 `DashScopeError`,携带 `message`、`code`、 +`status_code`、`request_id`、`body` 与 `headers`。捕获基类即可处理任何 +SDK 或 API 失败,也可捕获具体子类做更精细的控制。 + +## 基类与错误码 + +::: dashscope.errors.DashScopeError + +::: dashscope.errors.ErrorCode + +::: dashscope.errors.SdkError + +## 传输与校验错误 + +::: dashscope.errors.APIConnectionError + +::: dashscope.errors.APITimeoutError + +::: dashscope.errors.APIResponseValidationError + +## HTTP 状态错误 + +::: dashscope.errors.APIStatusError + +::: dashscope.errors.BadRequestError + +::: dashscope.errors.AuthenticationError + +::: dashscope.errors.PermissionDeniedError + +::: dashscope.errors.NotFoundError + +::: dashscope.errors.RequestTooLargeError + +::: dashscope.errors.RateLimitError + +::: dashscope.errors.InternalServerError + +::: dashscope.errors.ServiceUnavailableError + +::: dashscope.errors.GatewayTimeoutError + +::: dashscope.errors.ContentFilterError + +## WebSocket 错误 + +::: dashscope.errors.WsEventError + +::: dashscope.errors.WsStateError + +::: dashscope.errors.WsQueueCapacityExceededError + +::: dashscope.errors.WsBinaryOwnerConflictError \ No newline at end of file diff --git a/docs/zh/reference/legacy.md b/docs/zh/reference/legacy.md new file mode 100644 index 00000000..0ca2e08c --- /dev/null +++ b/docs/zh/reference/legacy.md @@ -0,0 +1,181 @@ +--- +description: "归档于 dashscope.legacy_1x 的冻结 1.x 接口,为向后兼容保留。" +status: deprecated +--- +# 旧版 1.x API + +1.x API 类已归档至 `dashscope.legacy_1x`,为保持向后兼容仍可从 +`dashscope` 根模块导入(`from dashscope import Generation` 仍可用)。 +兼容层已冻结:不再新增能力。新代码请使用 2.0 [客户端](client.md)。 + +!!! warning "冻结层" + 1.x 接口不再新增能力。访问 `Assistants` / `Threads` + 还会触发 `DeprecationWarning`。 + +## 文本生成 + +::: dashscope.legacy_1x.aigc.generation.Generation + +::: dashscope.legacy_1x.aigc.generation.AioGeneration + +::: dashscope.legacy_1x.aigc.code_generation.CodeGeneration + +::: dashscope.legacy_1x.aigc.conversation.Conversation + +::: dashscope.legacy_1x.aigc.conversation.History + +::: dashscope.legacy_1x.aigc.conversation.HistoryItem + +## 多模态对话 + +::: dashscope.legacy_1x.aigc.multimodal_conversation.MultiModalConversation + +::: dashscope.legacy_1x.aigc.multimodal_conversation.AioMultiModalConversation + +## 图像与视频生成 + +::: dashscope.legacy_1x.aigc.image_synthesis.ImageSynthesis + +::: dashscope.legacy_1x.aigc.image_synthesis.AioImageSynthesis + +::: dashscope.legacy_1x.aigc.image_generation.ImageGeneration + +::: dashscope.legacy_1x.aigc.image_generation.AioImageGeneration + +::: dashscope.legacy_1x.aigc.video_synthesis.VideoSynthesis + +::: dashscope.legacy_1x.aigc.video_synthesis.AioVideoSynthesis + +## 向量嵌入 + +::: dashscope.legacy_1x.embeddings.text_embedding.TextEmbedding + +::: dashscope.legacy_1x.embeddings.batch_text_embedding.BatchTextEmbedding + +::: dashscope.legacy_1x.embeddings.batch_text_embedding_response.BatchTextEmbeddingResponse + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.MultiModalEmbedding + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.AioMultiModalEmbedding + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.MultiModalEmbeddingItemText + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.MultiModalEmbeddingItemImage + +::: dashscope.legacy_1x.embeddings.multimodal_embedding.MultiModalEmbeddingItemAudio + +## 重排序 + +::: dashscope.legacy_1x.rerank.TextReRank + +::: dashscope.legacy_1x.rerank.AioTextReRank + +## NLP 理解 + +::: dashscope.legacy_1x.nlp.understanding.Understanding + +## 应用调用 + +::: dashscope.legacy_1x.app.application.Application + +::: dashscope.legacy_1x.app.application.ApplicationResponse + +## 语音合成(1.x) + +::: dashscope.legacy_1x.audio.tts.speech_synthesizer.SpeechSynthesizer + +::: dashscope.legacy_1x.audio.tts.speech_synthesizer.ResultCallback + +::: dashscope.legacy_1x.audio.tts.speech_synthesizer.SpeechSynthesisResult + +::: dashscope.legacy_1x.audio.http_tts.http_speech_synthesizer.HttpSpeechSynthesizer + +::: dashscope.legacy_1x.audio.tts_v2.speech_synthesizer.SpeechSynthesizer + +::: dashscope.legacy_1x.audio.tts_v2.speech_synthesizer.ResultCallback + +::: dashscope.legacy_1x.audio.tts_v2.enrollment.VoiceEnrollmentService + +::: dashscope.legacy_1x.audio.qwen_tts.speech_synthesizer.SpeechSynthesizer + +::: dashscope.legacy_1x.audio.qwen_tts_realtime.qwen_tts_realtime.QwenTtsRealtime + +::: dashscope.legacy_1x.audio.qwen_tts_realtime.qwen_tts_realtime.QwenTtsRealtimeCallback + +## 语音识别(1.x) + +::: dashscope.legacy_1x.audio.asr.recognition.Recognition + +::: dashscope.legacy_1x.audio.asr.recognition.RecognitionCallback + +::: dashscope.legacy_1x.audio.asr.recognition.RecognitionResult + +::: dashscope.legacy_1x.audio.asr.transcription.Transcription + +::: dashscope.legacy_1x.audio.asr.asr_phrase_manager.AsrPhraseManager + +::: dashscope.legacy_1x.audio.asr.translation_recognizer.TranslationRecognizerRealtime + +::: dashscope.legacy_1x.audio.asr.translation_recognizer.TranslationRecognizerChat + +::: dashscope.legacy_1x.audio.asr.translation_recognizer.TranslationRecognizerCallback + +::: dashscope.legacy_1x.audio.qwen_asr.qwen_transcription.QwenTranscription + +## Omni 实时(1.x) + +::: dashscope.legacy_1x.audio.qwen_omni.omni_realtime.OmniRealtimeConversation + +::: dashscope.legacy_1x.audio.qwen_omni.omni_realtime.OmniRealtimeCallback + +## 文件与模型(1.x) + +::: dashscope.legacy_1x.files.Files + +::: dashscope.legacy_1x.models.Models + +## 微调与部署(1.x) + +::: dashscope.legacy_1x.finetune.finetunes.FineTunes + +::: dashscope.legacy_1x.finetune.deployments.Deployments + +## 分词器 + +::: dashscope.legacy_1x.tokenizers.Tokenization + +::: dashscope.legacy_1x.tokenizers.Tokenizer + +::: dashscope.legacy_1x.tokenizers.get_tokenizer + +::: dashscope.legacy_1x.tokenizers.list_tokenizers + +## Assistants 与 Threads(已弃用) + +Assistants API 已弃用,访问这些名称会触发 `DeprecationWarning`。 + +::: dashscope.legacy_1x.assistants.assistants.Assistants + +::: dashscope.legacy_1x.assistants.assistant_types.Assistant + +::: dashscope.legacy_1x.threads.threads.Threads + +::: dashscope.legacy_1x.threads.thread_types.Thread + +::: dashscope.legacy_1x.threads.thread_types.ThreadMessage + +::: dashscope.legacy_1x.threads.messages.messages.Messages + +::: dashscope.legacy_1x.threads.runs.runs.Runs + +::: dashscope.legacy_1x.threads.thread_types.Run + +::: dashscope.legacy_1x.threads.runs.steps.Steps + +::: dashscope.legacy_1x.threads.thread_types.RunStep + +## 共享会话辅助函数 + +::: dashscope.legacy_1x.api_entities.http_request.close_shared_sync_session + +::: dashscope.legacy_1x.api_entities.aio_session.close_shared_aio_session \ No newline at end of file diff --git a/docs/zh/reference/protocols.md b/docs/zh/reference/protocols.md new file mode 100644 index 00000000..34bd8bcb --- /dev/null +++ b/docs/zh/reference/protocols.md @@ -0,0 +1,32 @@ +--- +description: "native、OpenAI 兼容与 Anthropic 兼容协议适配器 API 参考。" +--- +# 协议适配器(Protocols) + +`dashscope.protocols` 在不同传输协议之间转换对话请求与响应, +同一个 `client.chat.completions` 调用可以使用 DashScope 原生协议、 +OpenAI 兼容协议或 Anthropic 兼容协议。通过 `Client(protocol="openai")` +(或 `protocol` 配置项 / `DASHSCOPE_PROTOCOL` 环境变量)选择; +合法值为 `native`、`openai`、`anthropic`。 + +!!! tip "优先级" + 显式 `Client(protocol=...)` 参数优先于 `protocol` 配置项, + 后者优先于 `DASHSCOPE_PROTOCOL` 环境变量。 + +## 基础契约 + +::: dashscope.protocols.base.ChatProtocol + +::: dashscope.protocols.base.ChatRequest + +## 适配器 + +::: dashscope.protocols.native.NativeProtocol + +::: dashscope.protocols.openai.OpenAIProtocol + +::: dashscope.protocols.anthropic.AnthropicProtocol + +## 注册表 + +::: dashscope.protocols.get_protocol \ No newline at end of file diff --git a/docs/zh/reference/resources.md b/docs/zh/reference/resources.md new file mode 100644 index 00000000..d20670a8 --- /dev/null +++ b/docs/zh/reference/resources.md @@ -0,0 +1,217 @@ +--- +description: "客户端资源命名空间 API 参考:向量嵌入、图像、视频、文件、微调等。" +--- +# 客户端资源(Resources) + +挂载在 `Client` 与 `AsyncClient` 上的资源命名空间。 +各节列出同步与异步类及其响应模型。 + +## 向量嵌入(Embeddings) + +`client.embeddings` —— 文本向量调用与批量任务。 + +::: dashscope.resources.embeddings.Embeddings + +::: dashscope.resources.embeddings.AsyncEmbeddings + +::: dashscope.resources.embeddings.EmbeddingJobs + +::: dashscope.resources.embeddings.AsyncEmbeddingJobs + +::: dashscope.resources.embeddings.Embedding + +::: dashscope.resources.embeddings.EmbeddingResponse + +## 多模态(Multimodal) + +`client.multimodal` —— 多模态对话与向量嵌入。 + +::: dashscope.resources.multimodal.Multimodal + +::: dashscope.resources.multimodal.AsyncMultimodal + +::: dashscope.resources.multimodal.chat.MultimodalChat + +::: dashscope.resources.multimodal.chat.AsyncMultimodalChat + +::: dashscope.resources.multimodal.embeddings.MultimodalEmbeddings + +::: dashscope.resources.multimodal.embeddings.AsyncMultimodalEmbeddings + +::: dashscope.resources.multimodal.embeddings.EmbeddingItem + +## 重排序(Rerank) + +`client.rerank` —— 文档重排序。 + +::: dashscope.resources.rerank.Rerank + +::: dashscope.resources.rerank.AsyncRerank + +::: dashscope.resources.rerank.RerankResponse + +::: dashscope.resources.rerank.RerankResult + +::: dashscope.resources.rerank.RerankDocument + +## 图像(Images) + +`client.images` —— 图像生成任务。 + +::: dashscope.resources.images.Images + +::: dashscope.resources.images.AsyncImages + +::: dashscope.resources.images.ImageJobs + +::: dashscope.resources.images.AsyncImageJobs + +## 视频(Videos) + +`client.videos` —— 视频生成任务。 + +::: dashscope.resources.videos.Videos + +::: dashscope.resources.videos.AsyncVideos + +::: dashscope.resources.videos.VideoJobs + +::: dashscope.resources.videos.AsyncVideoJobs + +## 文件(Files) + +`client.files` —— 文件上传、列表与删除。 + +::: dashscope.resources.files.Files + +::: dashscope.resources.files.AsyncFiles + +::: dashscope.resources.files.File + +::: dashscope.resources.files.FileList + +::: dashscope.resources.files.DeletionStatus + +## 模型(Models) + +`client.models` —— 模型目录。 + +::: dashscope.resources.models.Models + +::: dashscope.resources.models.AsyncModels + +::: dashscope.resources.models.Model + +::: dashscope.resources.models.ModelList + +## 微调(Fine-tunes) + +`client.fine_tunes` —— 微调任务、日志与事件。 + +::: dashscope.resources.fine_tunes.FineTunes + +::: dashscope.resources.fine_tunes.AsyncFineTunes + +::: dashscope.resources.fine_tunes.FineTune + +::: dashscope.resources.fine_tunes.FineTuneList + +::: dashscope.resources.fine_tunes.JobLogs + +::: dashscope.resources.fine_tunes.FineTuneEvent + +## 部署(Deployments) + +`client.deployments` —— 模型部署。 + +::: dashscope.resources.deployments.Deployments + +::: dashscope.resources.deployments.AsyncDeployments + +::: dashscope.resources.deployments.Deployment + +::: dashscope.resources.deployments.DeploymentList + +::: dashscope.resources.deployments.DeploymentEvent + +## 应用(Apps) + +`client.apps` —— 应用补全(智能体 / 工作流)。 + +::: dashscope.resources.apps.Apps + +::: dashscope.resources.apps.AsyncApps + +::: dashscope.resources.apps.AppCompletions + +::: dashscope.resources.apps.AsyncAppCompletions + +::: dashscope.resources.apps.AppCompletion + +::: dashscope.resources.apps.AppStream + +::: dashscope.resources.apps.AsyncAppStream + +::: dashscope.resources.apps.AppUsage + +::: dashscope.resources.apps.Thought + +::: dashscope.resources.apps.DocReference + +::: dashscope.resources.apps.WorkflowMessage + +## 听悟(TingWu) + +`client.tingwu` —— 会议转写与分析。 + +::: dashscope.resources.tingwu.TingWu + +::: dashscope.resources.tingwu.AsyncTingWu + +::: dashscope.resources.tingwu.TingWuRealtime + +::: dashscope.resources.tingwu.TingWuResult + +## 决策(Decision) + +`client.decision` —— 结构化决策 / 评判调用。 + +::: dashscope.resources.decision.Decision + +::: dashscope.resources.decision.AsyncDecision + +::: dashscope.resources.decision.DecisionResponse + +::: dashscope.resources.decision.DecisionAnswer + +::: dashscope.resources.decision.ChoiceQuestion + +::: dashscope.resources.decision.NoulQuestion + +::: dashscope.resources.decision.ScoreQuestion + +## 分词(Tokenization) + +`client.tokenization` —— Token 计数。 + +::: dashscope.resources.tokenization.Tokenization + +::: dashscope.resources.tokenization.AsyncTokenization + +::: dashscope.resources.tokenization.TokenCount + +## 强化学习(Reinforcement learning) + +`client.rl` —— 智能体 RL 数据集、函数与任务。 + +::: dashscope.resources.reinforcement_learning.Rl + +::: dashscope.resources.reinforcement_learning.AsyncRl + +::: dashscope.resources.reinforcement_learning.RlJobs + +::: dashscope.resources.reinforcement_learning.AsyncRlJobs + +::: dashscope.resources.reinforcement_learning.RegisteredFunctions + +::: dashscope.resources.reinforcement_learning.UploadedData \ No newline at end of file diff --git a/docs/zh/reference/types.md b/docs/zh/reference/types.md new file mode 100644 index 00000000..3853ef29 --- /dev/null +++ b/docs/zh/reference/types.md @@ -0,0 +1,61 @@ +--- +description: "共享 pydantic 模型 API 参考:消息、补全、分页与辅助函数。" +--- +# 类型(Types) + +消息、补全、响应与分页的共享 pydantic 模型,以及消息规范化辅助函数。 +大部分名称可从 `dashscope.types` 直接导入。 + +## 消息与内容片段 + +::: dashscope.types.messages.Message + +::: dashscope.types.messages.TextPart + +::: dashscope.types.messages.ImagePart + +::: dashscope.types.messages.AudioPart + +::: dashscope.types.messages.VideoPart + +::: dashscope.types.messages.ToolCall + +::: dashscope.types.messages.ToolCallFunction + +## 补全模型 + +::: dashscope.types.completions.ChatCompletion + +::: dashscope.types.completions.ChatCompletionChunk + +::: dashscope.types.completions.ChatCompletionMessage + +::: dashscope.types.completions.Choice + +::: dashscope.types.completions.StreamChoice + +::: dashscope.types.completions.Delta + +::: dashscope.types.completions.SearchInfo + +::: dashscope.types.completions.SearchResult + +## 通用与分页 + +::: dashscope.types.common.ResponseBase + +::: dashscope.types.common.Usage + +::: dashscope.types.common.JobStatus + +::: dashscope.types.pagination.BasePage + +## 辅助函数 + +::: dashscope.types.messages.normalize_messages + +::: dashscope.types.messages.extract_text + +::: dashscope.types.completions.parse_completion + +::: dashscope.types.completions.parse_chunk \ No newline at end of file diff --git a/docs/zh/release-notes.md b/docs/zh/release-notes.md new file mode 100644 index 00000000..74883cbd --- /dev/null +++ b/docs/zh/release-notes.md @@ -0,0 +1,43 @@ +--- +description: "dashscope Python SDK 发行说明与变更日志指引,含 2.0 亮点。" +--- +# 发行说明 + +逐版本的权威变更日志发布在 +[GitHub Releases](https://github.com/dashscope/dashscope-sdk-python/releases)。 +本页概述主要版本线并链接近期 tag。 +当前 SDK 版本:**{{ sdk_version }}**。 + +## 近期发布 + +| Tag | 说明 | +| --- | --- | +| [v2.1.0](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.1.0) | [请参阅发布页面](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.1.0) | +| [v2.0.4](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.4) | [请参阅发布页面](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.4) | +| [v2.0.3](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.3) | [请参阅发布页面](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.3) | +| [v2.0.2](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.2) | [请参阅发布页面](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.2) | +| [v2.0.1](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.1) | [请参阅发布页面](https://github.com/dashscope/dashscope-sdk-python/releases/tag/v2.0.1) | + +## 2.0 亮点 + +2.0 引入了参照 OpenAI SDK 人体工学的资源式客户端: + +- **入口** —— `client.chat.completions.create(...)` 取代模块级静态类; + 一行式 `dashscope.chat("qwen-plus", "...")`。 +- **响应** —— 类型化对象(`resp.output_text`、`resp.usage.total_tokens`), + 取代原始 dict 式结果。 +- **错误** —— 默认抛出类型化 `DashScopeError` 异常。 +- **流式** —— `ChatStream` 提供 `.text_stream`、`.reasoning_stream` 与 + `.get_final_message()`。 +- **协议** —— 一个客户端通过 `protocol=` 使用 `native`、`openai` 或 + `anthropic`。 +- **异步** —— `dashscope.AsyncClient()` 镜像同步接口。 +- **连接** —— 每客户端一个 keep-alive 连接池,跨资源共享。 +- **配置** —— 分层:参数 → `dashscope.settings` → 环境变量 → + `~/.dashscope/config.toml`。 + +## 1.x 版本线 + +1.x API 为向后兼容保留在 `dashscope.legacy_1x` 下,仍可从 `dashscope` +根模块导入。该层已冻结:新能力只进入 2.x 接口。 +见[旧版 1.x](reference/legacy.md)。 \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..e8f2dce4 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,172 @@ +site_name: DashScope Python SDK +site_description: dashscope 2.0 Python SDK documentation — sync/async client and API reference for Alibaba Cloud Model Studio (DashScope) +site_url: https://dashscope.github.io/dashscope-sdk-python/ +repo_url: https://github.com/dashscope/dashscope-sdk-python +repo_name: dashscope/dashscope-sdk-python + +docs_dir: docs +site_dir: site + +theme: + name: material + custom_dir: docs/overrides + language: en + logo: assets/logo.svg + favicon: assets/logo.svg + features: + - navigation.tabs + - navigation.tabs.sticky + - navigation.path + - navigation.sections + - navigation.top + - navigation.footer + - search.suggest + - search.highlight + - content.code.copy + - toc.follow + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: white + accent: indigo + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: indigo + toggle: + icon: material/brightness-4 + name: Switch to light mode + icon: + repo: fontawesome/brands/github + +# FastAPI-style template tweaks (link color on white header, active tab +# underline, centered page title) +extra_css: + - stylesheets/extra.css + +markdown_extensions: + - admonition + - attr_list + - md_in_html + - tables + - toc: + permalink: true + - pymdownx.details + - pymdownx.superfences + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.tabbed: + alternate_style: true + +plugins: + - search: + lang: + - en + - zh + # i18n must come after search and before mkdocstrings; Material renders + # the language selector in the header automatically from this config. + - i18n: + docs_structure: folder + languages: + - locale: en + default: true + name: English + build: true + - locale: zh + name: 简体中文 + build: true + nav_translations: + Features: 特征 + Learn: 学习 + Quickstart: 快速开始 + Migrating from 1.x: 从 1.x 迁移 + Guides: 专题指南 + Capability recipes: 能力速查示例 + Qwen Live (realtime voice): Qwen Live(实时语音) + CLI: 命令行工具 + Reference: 参考 + Client & Configuration: 客户端与配置 + Chat: 对话(Chat) + Audio: 语音(Audio) + Client Resources: 客户端资源 + Protocols: 协议适配器 + Agentic RL: 强化学习微调 + Types: 类型(Types) + Errors: 错误(Errors) + Devkit: 开发工具 + Legacy 1.x: 旧版 1.x + Resources: 资源 + Developer Guide: 开发者指南 + Examples (GitHub): 示例(GitHub) + Help & Issues: 帮助与问题反馈 + About: 关于 + Release Notes: 发行说明 + # Resolve cross-references to the same-language page when an identifier + # exists in both locales (en at the root, zh under zh/). + - autorefs: + resolve_closest: true + - mkdocstrings: + handlers: + python: + paths: [.] + options: + docstring_style: google + show_source: true + show_root_heading: true + show_root_full_path: false + members_order: source + separate_signature: true + show_signature_annotations: true + filters: + - "!^_" + +nav: + - DashScope Python SDK: index.md + - Features: features.md + - Learn: + - Quickstart: quickstart.md + - Migrating from 1.x: migration.md + - Guides: + - Capability recipes: guides/recipes.md + - Qwen Live (realtime voice): guides/qwen-live-python-sdk.md + - CLI: cli.md + - Reference: + - Client & Configuration: reference/client.md + - Chat: reference/chat.md + - Audio: reference/audio.md + - Client Resources: reference/resources.md + - Protocols: reference/protocols.md + - AgentStudio: reference/agentstudio.md + - Agentic RL: reference/agentic-rl.md + - Types: reference/types.md + - Errors: reference/errors.md + - Devkit: reference/devkit.md + - Legacy 1.x: reference/legacy.md + - Resources: + - Developer Guide: develop.md + - Examples (GitHub): https://github.com/dashscope/dashscope-sdk-python/tree/main/examples + - Help & Issues: https://github.com/dashscope/dashscope-sdk-python/issues + - About: about.md + - Release Notes: release-notes.md + +# Maintenance notes are repo-only, not part of the site (README.md would +# conflict with index.md) +exclude_docs: | + README.md + README_zh.md + overrides/* + hooks.py + +hooks: + - docs/hooks.py + +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/dashscope/dashscope-sdk-python + - icon: fontawesome/brands/python + link: https://pypi.org/project/dashscope/ \ No newline at end of file diff --git a/requirements-doc.txt b/requirements-doc.txt index 3b353835..6d29112d 100644 --- a/requirements-doc.txt +++ b/requirements-doc.txt @@ -1,7 +1,10 @@ -docutils>=0.16.0 -myst_parser -recommonmark -sphinx>=5.3.0 -sphinx-book-theme -sphinx-copybutton -sphinx_markdown_tables +# MkDocs 2.0 removes the plugin system; Material/mkdocstrings require 1.x +mkdocs>=1.6,<2 +mkdocs-material>=9.5 +mkdocstrings[python]>=0.26 +# Multi-language site (English default + Chinese), FastAPI-style selector +mkdocs-static-i18n>=1.2 +# Signature formatting for mkdocstrings (separate_signature) +black +# Chinese search segmentation for the Material search plugin +jieba \ No newline at end of file diff --git a/setup.py b/setup.py index 45f5fabc..f74ffc4d 100644 --- a/setup.py +++ b/setup.py @@ -95,6 +95,11 @@ def run(self): author_email="dashscope@alibabacloud.com", license="Apache 2.0", url=url, + project_urls={ + "Documentation": "https://dashscope.github.io/dashscope-sdk-python/", + "Source": "https://github.com/dashscope/dashscope-sdk-python", + "Issues": "https://github.com/dashscope/dashscope-sdk-python/issues", + }, packages=setuptools.find_packages( exclude=("tests", "tests.*"), ), # pylint: disable=superfluous-parens From 895ab7dd2f37fbf47d33bf13f0e4c31276c23d6a Mon Sep 17 00:00:00 2001 From: luk384090-cloud Date: Tue, 17 Nov 2026 11:37:39 +0800 Subject: [PATCH 05/19] fix(pre-commit): exclude docs folder from stylelint hook - Added docs folder exclusion to stylelint configuration to avoid linting third-party styles - Aligned docs exclusion with existing mypy and pylint exemptions feat(dashscope): re-export applications subpackage as module - Re-exported applications subpackage for better type checking and stub merging - Ensured submodules under applications remain accessible to type checkers and griffe style(docs): add coding declaration and format hooks.py - Added UTF-8 coding declaration at the top of docs/hooks.py - Adjusted file formatting for consistency and clarity --- .pre-commit-config.yaml | 4 +++- dashscope/__init__.pyi | 7 ++++++- docs/hooks.py | 3 ++- 3 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index ffe2d8c9..b9d73cbd 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -206,7 +206,9 @@ repos: hooks: - id: stylelint files: \.(css)$ - exclude: '(.*css_third_party.*|^tests/legacy_1x/legacy/)' + # docs/ ships its own Material stylesheet without a stylelint config, + # matching the ^docs exemption already used by mypy and pylint. + exclude: '(.*css_third_party.*|^tests/legacy_1x/legacy/|^docs/)' args: [ '--fix' ] - repo: https://github.com/pre-commit/mirrors-prettier rev: 'v3.0.0' diff --git a/dashscope/__init__.pyi b/dashscope/__init__.pyi index 46a54671..f75be25f 100644 --- a/dashscope/__init__.pyi +++ b/dashscope/__init__.pyi @@ -41,11 +41,16 @@ def close_shared_sync_session() -> None: ... def set_region(region: str, workspace_id: Optional[str] = ...) -> None: ... # Lazily resolved compatibility modules. +# ``applications`` is a real 2.0 subpackage: re-export it as a module so type +# checkers and griffe keep access to its submodules (e.g. applications.finetune +# and applications.agentstudio). Declaring it as ``applications: Any`` would +# let griffe's stub merge shadow the submodule with a plain attribute. +from dashscope import applications as applications + aigc: Any agentstudio: Any api_entities: Any app: Any -applications: Any assistants: Any audio: Any cli: Any diff --git a/docs/hooks.py b/docs/hooks.py index 27f0a1b9..8cef8c51 100644 --- a/docs/hooks.py +++ b/docs/hooks.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- """MkDocs hooks: surface the SDK version from dashscope/version.py in pages. Pages opt in with the ``{{ sdk_version }}`` placeholder; the value is read @@ -25,4 +26,4 @@ def on_page_markdown(markdown, *, page, config, files): return markdown.replace( "{{ sdk_version }}", config.extra.get("sdk_version", "unknown"), - ) \ No newline at end of file + ) From fe029d469b76f9400972833ccaa92ddc2c77fe8a Mon Sep 17 00:00:00 2001 From: luk384090-cloud Date: Tue, 17 Nov 2026 13:09:27 +0800 Subject: [PATCH 06/19] fix(docs): replace SVG logo with PNG format - Update mkdocs.yml to use assets/logo.png for logo and favicon - Remove old SVG logo file from the docs/assets directory - Ensure logo images are consistently in PNG format for better compatibility --- docs/assets/logo.png | Bin 0 -> 73419 bytes docs/assets/logo.svg | 4 ---- mkdocs.yml | 4 ++-- 3 files changed, 2 insertions(+), 6 deletions(-) create mode 100644 docs/assets/logo.png delete mode 100644 docs/assets/logo.svg diff --git a/docs/assets/logo.png b/docs/assets/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..3e343cd43ea496d8c4b78517d51588bf6496c563 GIT binary patch literal 73419 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

xv2Vbhq;5ph^=#^L$B9Ha4409# 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∓r<~T){nm~w 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 - - - \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index e8f2dce4..4b0f67ab 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -11,8 +11,8 @@ theme: name: material custom_dir: docs/overrides language: en - logo: assets/logo.svg - favicon: assets/logo.svg + logo: assets/logo.png + favicon: assets/logo.png features: - navigation.tabs - navigation.tabs.sticky From 0559e461f5c9d349f71ea5fab4bc668a274b4817 Mon Sep 17 00:00:00 2001 From: "zhansheng.lzs" Date: Tue, 17 Nov 2026 13:57:57 +0800 Subject: [PATCH 07/19] fix(docs): clarify mock billing and sync-only audio APIs --- docs/en/features.md | 8 +++++--- docs/en/guides/recipes.md | 16 +++++++++++++--- docs/en/reference/devkit.md | 8 +++++--- docs/zh/features.md | 6 +++--- docs/zh/guides/recipes.md | 15 ++++++++++++--- docs/zh/reference/devkit.md | 8 +++++--- 6 files changed, 43 insertions(+), 18 deletions(-) diff --git a/docs/en/features.md b/docs/en/features.md index 9ac81dca..01ccf3e6 100644 --- a/docs/en/features.md +++ b/docs/en/features.md @@ -62,8 +62,10 @@ See [Errors](reference/errors.md) and [Devkit](reference/devkit.md). ## Offline development with dev mock -- `static` / `replay` / `record` modes exercise the full HTTP request path - without spending cloud tokens. +- `static` / `replay` modes exercise the HTTP request path offline without + spending cloud tokens. +- `record` sends real requests, which may incur charges, and saves the + responses for later offline replay. - Zero overhead when disabled; nothing is imported on the success path. See [Devkit](reference/devkit.md). @@ -93,4 +95,4 @@ See [CLI](cli.md). (`from dashscope import Generation`), implemented by frozen facades under `dashscope.legacy_1x`. -See [Legacy 1.x](reference/legacy.md). \ No newline at end of file +See [Legacy 1.x](reference/legacy.md). diff --git a/docs/en/guides/recipes.md b/docs/en/guides/recipes.md index 31f83766..9bbea5a7 100644 --- a/docs/en/guides/recipes.md +++ b/docs/en/guides/recipes.md @@ -5,8 +5,10 @@ description: "Copy-paste recipes for every dashscope 2.0 capability: multimodal, Short runnable snippets, one per capability. All of them assume an exported `DASHSCOPE_API_KEY` (see [Quickstart](../quickstart.md)) and use the sync -client; `AsyncClient` mirrors every call with `await`. Response fields are -typed — the [API Reference](../reference/client.md) documents each one. +client. `AsyncClient` mirrors the HTTP calls with `await`; the WebSocket +speech synthesis and file recognition examples below are sync-only. +Response fields are typed — the [API Reference](../reference/client.md) +documents each one. ## Multimodal understanding @@ -74,6 +76,10 @@ print(resp.results) ## Speech synthesis +!!! note "Sync-only WebSocket API" + Use `Client` for this example. `AsyncClient.audio.tts` does not expose + `synthesize()`; adding `await` does not make this call async. + `synthesize()` returns the concatenated audio bytes. ```python @@ -88,6 +94,10 @@ with open("out.mp3", "wb") as f: ## File recognition +!!! note "Sync-only WebSocket API" + Use `Client` for this example. `AsyncClient.audio.asr` does not expose + `recognize_file()`; adding `await` does not make this call async. + ```python for event in client.audio.asr.recognize_file( "audio.pcm", @@ -121,4 +131,4 @@ print(len(page.items), "models available") ``` See [Client Resources](../reference/resources.md) for the full resource -surface, including batch jobs and fine-tunes. \ No newline at end of file +surface, including batch jobs and fine-tunes. diff --git a/docs/en/reference/devkit.md b/docs/en/reference/devkit.md index f8e5fa49..92a595d5 100644 --- a/docs/en/reference/devkit.md +++ b/docs/en/reference/devkit.md @@ -6,8 +6,10 @@ description: "API reference for dev mock modes and local self-diagnosis." `dashscope.devkit` provides two opt-in developer aids with near-zero overhead when disabled. Nothing here is imported on the production success path. -- **Dev mock** — `static` / `replay` / `record` modes that exercise the full - 2.0 HTTP request path without spending cloud tokens. HTTP only; the +- **Dev mock** — `static` / `replay` / `record` modes that exercise the + 2.0 HTTP request path. `static` and `replay` run offline without spending + cloud tokens; `record` sends real requests to the service, which may incur + charges, and saves the responses for later replay. HTTP only; the WebSocket transport is not covered. Activate in code with `dashscope.enable_dev_mock(...)` or via `DASHSCOPE_DEV_MOCK=`. - **Self-diagnosis** — a local, bilingual rule table that turns a failed call @@ -40,4 +42,4 @@ The root module forwards the mock switches: `dashscope.enable_dev_mock`, ::: dashscope.devkit.diagnosis.render -::: dashscope.devkit.diagnosis.install_excepthook \ No newline at end of file +::: dashscope.devkit.diagnosis.install_excepthook diff --git a/docs/zh/features.md b/docs/zh/features.md index 2b365977..461004e8 100644 --- a/docs/zh/features.md +++ b/docs/zh/features.md @@ -60,8 +60,8 @@ dashscope 2.0 SDK 是面向阿里云百炼(Model Studio / DashScope)的 ## 用 dev mock 离线开发 -- `static` / `replay` / `record` 三种模式走通完整 HTTP 请求路径, - 不消耗云端 token。 +- `static` / `replay` 模式离线走通 HTTP 请求路径,不消耗云端 token。 +- `record` 会发送真实请求,可能产生费用,并保存响应供后续离线回放。 - 关闭时零开销;成功路径上不导入任何相关代码。 见[开发工具](reference/devkit.md)。 @@ -90,4 +90,4 @@ dashscope 2.0 SDK 是面向阿里云百炼(Model Studio / DashScope)的 (`from dashscope import Generation`),由 `dashscope.legacy_1x` 下 的冻结门面实现。 -见[旧版 1.x](reference/legacy.md)。 \ No newline at end of file +见[旧版 1.x](reference/legacy.md)。 diff --git a/docs/zh/guides/recipes.md b/docs/zh/guides/recipes.md index f8fad369..600bd448 100644 --- a/docs/zh/guides/recipes.md +++ b/docs/zh/guides/recipes.md @@ -4,8 +4,9 @@ description: "dashscope 2.0 各能力的即抄即用示例:多模态、图像 # 能力速查示例 每个能力一段可直接运行的短示例。均假设已导出 `DASHSCOPE_API_KEY` -(见[快速开始](../quickstart.md)),并使用同步客户端;`AsyncClient` -以 `await` 镜像全部调用。响应字段均为类型化对象, +(见[快速开始](../quickstart.md)),并使用同步客户端。`AsyncClient` +以 `await` 镜像 HTTP 调用;下方基于 WebSocket 的语音合成与文件识别 +示例仅支持同步客户端。响应字段均为类型化对象, [API 参考](../reference/client.md)逐一说明。 ## 多模态理解 @@ -73,6 +74,10 @@ print(resp.results) ## 语音合成 +!!! note "仅支持同步的 WebSocket API" + 此示例需使用 `Client`。`AsyncClient.audio.tts` 不提供 + `synthesize()`,不能仅通过添加 `await` 改为异步调用。 + `synthesize()` 返回拼接后的音频字节。 ```python @@ -87,6 +92,10 @@ with open("out.mp3", "wb") as f: ## 文件识别 +!!! note "仅支持同步的 WebSocket API" + 此示例需使用 `Client`。`AsyncClient.audio.asr` 不提供 + `recognize_file()`,不能仅通过添加 `await` 改为异步调用。 + ```python for event in client.audio.asr.recognize_file( "audio.pcm", @@ -120,4 +129,4 @@ print(len(page.items), "个可用模型") ``` 完整资源接口(含批量任务与微调)见 -[客户端资源](../reference/resources.md)。 \ No newline at end of file +[客户端资源](../reference/resources.md)。 diff --git a/docs/zh/reference/devkit.md b/docs/zh/reference/devkit.md index 3b832665..b8ec98db 100644 --- a/docs/zh/reference/devkit.md +++ b/docs/zh/reference/devkit.md @@ -6,8 +6,10 @@ description: "dev mock 模式与本地自诊断 API 参考。" `dashscope.devkit` 提供两个可选的开发辅助能力,关闭时几乎零开销, 生产成功路径上不会导入本包。 -- **Dev mock** —— `static` / `replay` / `record` 三种模式,不消耗云端 - token 即可走通完整的 2.0 HTTP 请求路径。仅覆盖 HTTP,不覆盖 +- **Dev mock** —— `static` / `replay` / `record` 三种模式走通 + 2.0 HTTP 请求路径。`static` 与 `replay` 离线运行,不消耗云端 + token;`record` 会向服务发送真实请求,可能产生费用,并保存响应 + 供后续回放。仅覆盖 HTTP,不覆盖 WebSocket 传输。代码中用 `dashscope.enable_dev_mock(...)` 启用, 或设置 `DASHSCOPE_DEV_MOCK=`。 - **自诊断** —— 本地双语规则表,把失败调用转化为结构化的修复建议, @@ -40,4 +42,4 @@ description: "dev mock 模式与本地自诊断 API 参考。" ::: dashscope.devkit.diagnosis.render -::: dashscope.devkit.diagnosis.install_excepthook \ No newline at end of file +::: dashscope.devkit.diagnosis.install_excepthook From 3ef9176e63df6cbdc91cf9ff902f849119fb9e06 Mon Sep 17 00:00:00 2001 From: luk384090-cloud Date: Tue, 17 Nov 2026 18:26:50 +0800 Subject: [PATCH 08/19] docs(mkdocs): improve sidebar and toc behavior for API reference pages - Disable system font stack due to Google Fonts blocking first paint in China - Limit sidebar "On this page" navigation depth to h3 headings - Adjust mkdocstrings rendering to use heading level 3 for roots - Prune "On this page" nav to show only h2 section titles on large API pages - Deduplicate injected CSS to prevent duplicates during i18n rebuild - Add localized aria-label for page actions navigation in main.html - Customize English and Chinese translations for "toc" as "On this page" text --- docs/hooks.py | 37 +++++++++++++ docs/overrides/main.html | 2 +- docs/overrides/partials/languages/en.html | 63 +++++++++++++++++++++++ docs/overrides/partials/languages/zh.html | 60 +++++++++++++++++++++ mkdocs.yml | 10 ++++ 5 files changed, 171 insertions(+), 1 deletion(-) create mode 100644 docs/overrides/partials/languages/en.html create mode 100644 docs/overrides/partials/languages/zh.html diff --git a/docs/hooks.py b/docs/hooks.py index 8cef8c51..066cdb46 100644 --- a/docs/hooks.py +++ b/docs/hooks.py @@ -7,6 +7,17 @@ import re from pathlib import Path +from mkdocs.structure.toc import AnchorLink, TableOfContents + +# Reference pages listing dozens of API symbols: even a section+symbol +# outline floods the sidebar (80-110 entries), so their "On this page" +# nav keeps only the h2 section titles. Applies to both locales. +_SECTION_ONLY_TOC_PAGES = { + "reference/agentstudio.md", + "reference/legacy.md", + "reference/resources.md", +} + def _read_version(docs_dir: str) -> str: source = Path(docs_dir).parent / "dashscope" / "version.py" @@ -19,9 +30,35 @@ def _read_version(docs_dir: str) -> str: def on_config(config): config.extra["sdk_version"] = _read_version(config.docs_dir) + # mkdocstrings inserts its stylesheet on every per-locale on_config + # pass, so the i18n rebuild emits the link twice; keep first occurrence. + config.extra_css = list(dict.fromkeys(config.extra_css)) return config +def on_page_content(html, *, page, config, files): + # i18n folder structure prefixes src_uri with the locale (en/ or zh/) + parts = page.file.src_uri.split("/") + src = ( + "/".join(parts[1:]) if parts[0] in ("en", "zh") else page.file.src_uri + ) + if src in _SECTION_ONLY_TOC_PAGES: + # toc tokens nest sections under the leading h1; Material replaces + # the nav with that h1's children, so prune from the same place. + items = list(page.toc) + if items and items[0].level == 1: + items = items[0].children + sections = [ + AnchorLink(item.title, item.id, item.level) + for item in items + if item.level == 2 + ] + if sections: + sections[0].active = True + page.toc = TableOfContents(sections) + return html + + def on_page_markdown(markdown, *, page, config, files): return markdown.replace( "{{ sdk_version }}", diff --git a/docs/overrides/main.html b/docs/overrides/main.html index b4a0e920..3014986d 100644 --- a/docs/overrides/main.html +++ b/docs/overrides/main.html @@ -4,7 +4,7 @@ {% block content %} {{ super() }} {% set zh = (i18n_page_locale | default("en")) == "zh" %} -