jiuzhang-sdk 0.1.0a10

九章光量子真机云接入软件包（jiuzhang SDK）

jiuzhang SDK 开发说明

本目录是 jiuzhang Python SDK 的源码工程。仓库根 README.md 面向用户和外部 协作方，本文件面向 SDK 开发维护。

当前主线

当前主线是九章云平台 HTTP SDK：

Python / Jupyter
  -> jiuzhang SDK
  -> 九章云平台 API / 本地九章云平台 Mock
  -> 天衍适配器
  -> 天衍平台 / tianyan-Mock

SDK 不直接请求天衍平台，不直接请求 tianyan-Mock，也不保留早期 TCP 真机直连 协议线。

工程结构

code/
├── pyproject.toml
├── README.md
├── src/jiuzhang/
│   ├── __init__.py
│   ├── auth/              # TokenManager
│   ├── cloud/             # CloudClient / HttpTransport
│   ├── gbs/               # GBSParams / GBSResult / analysis / mock
│   ├── jupyter.py         # Notebook helpers
│   ├── settings.py        # Settings.from_env()
│   ├── errors.py
│   ├── exceptions.py
│   └── result.py
└── tests/
    ├── unit/
    └── integration/

本地开发

使用本机 jzsdk conda 环境：

conda activate jzsdk
cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk\code
pip install -e ".[dev,jupyter]"

质量检查：

ruff format src tests
ruff check src tests
mypy src
pytest tests

公开 API

from jiuzhang import CloudClient, TokenManager
from jiuzhang import GBSParams, GBSResult, parse_gbs_result
from jiuzhang.gbs.analysis import photon_count_histogram
from jiuzhang.gbs.mock import generate_mock_samples

云平台接口

SDK 当前请求九章云平台公开接口：

POST /estimate
POST /tasks/submit
GET  /tasks/{task_id}

认证头：

X-Jiuzhang-API-Key: <api_key>

提交任务时自动携带：

X-Request-Id: <uuid>

所有云平台响应先检查 code，只有 code == 0 才视为业务成功。

本地 Mock

cd C:\Users\Administrator\Documents\Project\gitlab\jiuzhang_sdk
python local_test/mock_cloud_platform/mock_cloud_platform.py --port 18081 --mode standalone

SDK 测试和示例中的 base_url 指向本地九章云平台 Mock：

http://127.0.0.1:18081

版本

当前版本：0.1.0a10。

License

Proprietary — Copyright © 2026 九章量子.