[docs] Improve API reference documentation by Artimislyy · Pull Request #65 · Ascend/ray-ascend

Artimislyy · 2026-06-02T11:25:16Z

Description

Standardized format for each API with clear sections: Description, Parameters, Returns, Raises, Notes, and Examples
Added complete code examples with proper imports and realistic usage patterns
Improved clarity on when and where each function should be called

Fix

[doc] More clear and detailed API docs for users #58

ascend-robot · 2026-06-02T11:25:26Z

CLA Signature Guide

@Artimislyy , thanks for your pull request.

The following commit(s) are not associated with a signed Contributor License Agreement (CLA).

Commit	Reason
cb8f1583 docs: modify API reference docum...	the email used in the commit is not linked to a signed CLA! please verify that it matches the email you used when signing the CLA.

To sign CLA, click here.

To check if your email is configured correctly, refer to the FAQs.

Once you've signed the CLA or updating your email, please comment /check-cla to revalidate CLA status.

ascend-robot · 2026-06-02T12:21:58Z

CLA Signature Guide

@Artimislyy , thanks for your pull request.

The following commit(s) are not associated with a signed Contributor License Agreement (CLA).

Commit	Reason
cb8f1583 docs: modify API reference docum...	the email used in the commit is not linked to a signed CLA! please verify that it matches the email you used when signing the CLA.

To sign CLA, click here.

To check if your email is configured correctly, refer to the FAQs.

Once you've signed the CLA or updating your email, please comment /check-cla to revalidate CLA status.

ascend-robot · 2026-06-03T01:23:05Z

CLA Signature Guide

@Artimislyy , thanks for your pull request.

The following commit(s) are not associated with a signed Contributor License Agreement (CLA).

Commit	Reason
cb8f1583 docs: modify API reference docum...	the email used in the commit is not linked to a signed CLA! please verify that it matches the email you used when signing the CLA.

To sign CLA, click here.

To check if your email is configured correctly, refer to the FAQs.

Once you've signed the CLA or updating your email, please comment /check-cla to revalidate CLA status.

dpj135 · 2026-06-03T01:26:34Z

Add cleanup_yr_resources()

tianyi-ge · 2026-06-03T01:41:31Z

+    - `["npu"]` for NPU tensors only
+    - `["npu", "cpu"]` for NPU and CPU tensors
+    - `["cpu"]` for CPU tensors only
+    - `None` (default) for both `["npu", "cpu"]`


now the default value is ["npu", "cpu"]. check ray_ascend/__init__.py

tianyi-ge · 2026-06-03T01:43:08Z

+
+**Notes:**
+
+- Must be called in both the driver process and each actor's `__init__`


Requires Ray >= 2.55

tianyi-ge · 2026-06-03T01:47:05Z

+| Variable | Default | Description |
+| --- | --- | --- |
+| `YR_DS_INIT_MODE` | `metastore` | Initialization mode (`metastore` or `etcd`) |
+| `YR_DS_WORKER_PORT` | `31501` | YR DS worker port |


YR DS worker port -> openYuanrong Datasystem worker port

tianyi-ge · 2026-06-03T01:47:58Z

+    @ray.method(tensor_transport="YR")
+    def transfer_cpu_tensor_via_rdma(self):
+        return torch.zeros(1024)
+```


add a real use case e.g. driver calls transfer_cpu_tensor_via_rdma or transfer_npu_tensor_via_hccs and ray.get

tianyi-ge · 2026-06-03T01:48:17Z

+    backend="HCCL",
+    group_name="my_group",
+)
+```


add a real case e.g. call allreduce on each actor

tianyi-ge · 2026-06-03T01:50:46Z

+
+- Must be called in both the driver process and each actor's `__init__`
+- Environment variables should be set in the driver process before calling
+- YR backend initialization happens once across the cluster via a named actor


note that tensor_transport is case-insensitive. YR/yr both work; HCCL/hccl both work.

tianyi-ge · 2026-06-03T02:07:44Z

use pre-commit before commit https://ascend.github.io/ray-ascend/developer_guide/#coding-standards-and-submission

ascend-robot · 2026-06-03T06:29:26Z

CLA Signature Guide

@Artimislyy , thanks for your pull request.

The following commit(s) are not associated with a signed Contributor License Agreement (CLA).

Commit	Reason
cb8f1583 docs: modify API reference docum...	the email used in the commit is not linked to a signed CLA! please verify that it matches the email you used when signing the CLA.

To sign CLA, click here.

To check if your email is configured correctly, refer to the FAQs.

Once you've signed the CLA or updating your email, please comment /check-cla to revalidate CLA status.

dpj135 · 2026-06-03T06:58:44Z

Please add signature to commit info.

Commit 06ec2fdcdd5ae96c39134c71eb04336310303c3c is missing Signed-off-by
Commit e3687f617e21f2aed65a0607d9e454ff8390c655 is missing Signed-off-by
Commit 45bb4bf871cdaca3e19cc511f11d6156012e9774 is missing Signed-off-by
Commit c902d162753dfd94a979f6ec3c9b87ab8f036a44 is missing Signed-off-by
Commit cb6812d9e9371fe6b680f3e5dcee0e1470eff0aa is missing Signed-off-by
Commit 11e5d5c404769e6a5cefa4d898bc2470d0e5c7ec is missing Signed-off-by

dpj135 · 2026-06-03T07:03:35Z

 ```

-Must be called in both the driver process and each actor's `__init__`.
+## cleanup_yr_resources


cleanup_yr_resources is used to clean datasystem workers and single controller initialized by register_yr_tensor_transport. I think they should be together to decrible.

dpj135 · 2026-06-03T07:09:44Z

+## cleanup_yr_resources

-### Environment Variables
+Clean up all YR resources. Delegates cleanup to coordinator, then kills the coordinator


Users don't know what the coordinator is. Perhaps we need more popular description.

dpj135 · 2026-06-03T07:11:17Z


-### Environment Variables
+Clean up all YR resources. Delegates cleanup to coordinator, then kills the coordinator
+actor.


we can tell users like "ray stop can also clean yr worker".

what may happen if users forgot cleanup yr

YrDsCoordinary is detached. This actor process will continue to exist until ray shutdown

tianyi-ge · 2026-06-03T08:17:35Z

+| `YR_DS_INIT_MODE`      | `metastore` | Initialization mode (`metastore` or `etcd`) |
+| `YR_DS_WORKER_PORT`    | `31501`     | openYuanRong Datasystem worker port         |
+| `YR_DS_METASTORE_PORT` | `2379`      | Metastore service port                      |
+| `YR_DS_ETCD_ADDRESS`   | -           | Etcd address (required for etcd mode)       |


if etcd mode but no etcd address is provided, is there any error message? @dpj135

Raises error when os.getenv("YR_DS_ETCD_ADDRESS")

ray-ascend/ray_ascend/utils/yr_utils.py

Line 669 in 15784db

raise RuntimeError("etcd mode requires etcd_address")

ok

tianyi-ge · 2026-06-03T08:19:37Z


-### Environment Variables
+Clean up all YR resources. Delegates cleanup to coordinator, then kills the coordinator
+actor.


what may happen if users forgot cleanup yr

tianyi-ge · 2026-06-03T08:22:20Z

            - ["npu", "cpu"] for NPU and CPU tensors
            - ["cpu"] for CPU tensors only
-            - None (default) for both ["npu", "cpu"]
+            - `None` (uses `["npu", "cpu"]` by default)


None is not allowed, should raise error

tianyi-ge · 2026-06-04T01:50:06Z

+    def transfer_npu_tensor(self):
+        return torch.tensor([1, 2, 3]).npu()
+
+actor = RayActor.remote()


In order to use hccl in tensor transport, you need to create collective group first. see

ray-ascend/tests/direct_transport/test_hccl_tensor_transport.py

Line 27 in 15784db

create_collective_group(

ascend-robot · 2026-06-04T07:24:44Z

CLA Signature Guide

@Artimislyy , thanks for your pull request.

The following commit(s) are not associated with a signed Contributor License Agreement (CLA).

Commit	Reason
cb8f1583 docs: modify API reference docum...	the email used in the commit is not linked to a signed CLA! please verify that it matches the email you used when signing the CLA.

To sign CLA, click here.

To check if your email is configured correctly, refer to the FAQs.

Once you've signed the CLA or updating your email, please comment /check-cla to revalidate CLA status.

ascend-robot · 2026-06-04T07:43:28Z

CLA Signature Guide

@Artimislyy , thanks for your pull request.

The following commit(s) are not associated with a signed Contributor License Agreement (CLA).

Commit	Reason
cb8f1583 docs: modify API reference docum...	the email used in the commit is not linked to a signed CLA! please verify that it matches the email you used when signing the CLA.

To sign CLA, click here.

To check if your email is configured correctly, refer to the FAQs.

Once you've signed the CLA or updating your email, please comment /check-cla to revalidate CLA status.

Signed-off-by: Artimislyy <2249614312@qq.com>

ascend-robot · 2026-06-04T08:34:49Z

CLA Signature Pass

Artimislyy, thanks for your pull request. All authors of the commits have signed the CLA. 👍

Signed-off-by: Artimislyy <2249614312@qq.com>

ascend-robot · 2026-06-04T10:47:33Z

CLA Signature Pass

Artimislyy, thanks for your pull request. All authors of the commits have signed the CLA. 👍

dpj135 · 2026-06-04T12:31:59Z

+        return torch.zeros(1024, device="npu")
+
+    @ray.method(tensor_transport="YR")
+    def transfer_cpu_tensor_via_rdma(self):


TODO: Support RDMA for cpu tensor transport

dpj135

lgtm

ascend-robot added the ascend-cla/no label Jun 2, 2026

tianyi-ge reviewed Jun 3, 2026

View reviewed changes

dpj135 reviewed Jun 3, 2026

View reviewed changes

tianyi-ge reviewed Jun 3, 2026

View reviewed changes

tianyi-ge reviewed Jun 4, 2026

View reviewed changes

Artimislyy force-pushed the doc/improve-api-reference branch from aa0a8ae to 24b1605 Compare June 4, 2026 07:43

docs: modify API reference documentation

9681123

Signed-off-by: Artimislyy <2249614312@qq.com>

Artimislyy force-pushed the doc/improve-api-reference branch from 24b1605 to 9681123 Compare June 4, 2026 08:34

ascend-robot added ascend-cla/yes and removed ascend-cla/no labels Jun 4, 2026

register_yr_tensor_transport(devices=[npu, cpu])

a363a5c

Signed-off-by: Artimislyy <2249614312@qq.com>

tianyi-ge approved these changes Jun 4, 2026

View reviewed changes

itianshu approved these changes Jun 4, 2026

View reviewed changes

dpj135 reviewed Jun 4, 2026

View reviewed changes

dpj135 approved these changes Jun 4, 2026

View reviewed changes

tianyi-ge merged commit 084ed7d into Ascend:master Jun 4, 2026
7 of 10 checks passed


		Notes:

		- Must be called in both the driver process and each actor's `__init__`

Conversation

Artimislyy commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Fix

Uh oh!

ascend-robot commented Jun 2, 2026

CLA Signature Guide

Uh oh!

ascend-robot commented Jun 2, 2026

CLA Signature Guide

Uh oh!

ascend-robot commented Jun 3, 2026

CLA Signature Guide

Uh oh!

dpj135 commented Jun 3, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tianyi-ge commented Jun 3, 2026

Uh oh!

ascend-robot commented Jun 3, 2026

CLA Signature Guide

Uh oh!

dpj135 commented Jun 3, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ascend-robot commented Jun 4, 2026

CLA Signature Guide

Uh oh!

ascend-robot commented Jun 4, 2026

CLA Signature Guide

Uh oh!

ascend-robot commented Jun 4, 2026

CLA Signature Pass

Uh oh!

ascend-robot commented Jun 4, 2026

CLA Signature Pass

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dpj135 left a comment

Choose a reason for hiding this comment

Uh oh!

Artimislyy commented Jun 2, 2026 •

edited

Loading