[Train][Doc] Update PyTorch Data Ingestion User Guide

[woshiyyya]

Why are these changes needed?

This PR improves framework migration steps to Ray Data for data ingest user guide.

Follow-up PRs should do a larger restructure to make this guide more readable:

Future restructure plans

Restructured the "Starting from PyTorch Data" section for better readability. The following PR will incorporate the following restructure:

• Introduction (don’t need a title)
  • Layout the structure of the doc
  • Comparing framework-native utilities v.s. Ray Data, and guide user to choose one or the other.
    • Add quick link to the corresponding for "Use Framework-native .." and "Use Ray Data" sections
    • Show the benefits of ray data (can include contents in the blog post)
• Use Ray Data
  • Quickstart (add code snippets for each subsection)
  • Loading data
  • Inputting and splitting data
  • …
  • Remaining Ray Data Usage guide (Splitting Dataset, ..., Performance tips)
• Use Framework-native Data Utilities
  • Quickstart
  • Code snippets for Torch,Lighting, and HF

Related issue number

Checks

• I've signed off every commit(by using the -s flag, i.e., git commit -s) in this PR.
• I've run scripts/format.sh to lint the changes in this PR.
• I've included any doc changes needed for https://docs.ray.io/en/master/.
  • I've added any new APIs to the API Reference. For example, if I added a
    method in Tune, I've added it in doc/source/tune/api/ under the
    corresponding .rst file.
• I've made sure the tests are passing. Note that there might be a few flaky tests, see the recent failures at https://flakey-tests.ray.io/
• Testing Strategy
  • Unit tests
  • Release tests
  • This PR is not tested :(

[matthewdeng]

Nice! Love the added benefits & cleaner steps!

[matthewdeng]

The original names were more explicit to make it clear that this is referring to the dataset framework, rather than the training framework.

[matthewdeng]

Suggested change

	Why using Ray Data?
	Comparison with Ray Data

[matthewdeng]

nit:

Suggested change

	1. Convert your PyTorch Dataset to a Ray Dataset and
	1. Convert your PyTorch Dataset to a Ray Dataset.

There are some other small typos/formatting errors that I'll review more thoroughly in a follow-up review.

[matthewdeng]

nit: I understand why you chose to do this but I'm also a little worried this might be confusing since Option 1 technically does also use Hugging Face Datasets.

[woshiyyya]

Oh I realized the difference now. Previously, this section aims at teaching users how to convert their HF dataset to Ray Dataset, then do training. But this PR tries to directly categorize on what we eventually use in the training function.

# prev
HF Dataset -> Ray Data -> HF Transformers
            HF Dataset -> HF Transformers

# now
Ray Data -> HF Transformers
HF Dataset -> HF Transformers

My consideration here is that we'd better not force everyone to take the "HF Dataset -> Ray Data" conversion step.

For example, their original datasets format could be parquet, and before onboarding Ray, they already build a HF Dataset from parquet file, then feed it to HF Trainer.

In this case, they can either build ray dataset from parquet or from HF dataset.

# Before onboarding Ray
raw data -> HF dataset -> HF transformer

# After onboarding Ray
option 1: raw data -> HF dataset -> Ray Data -> HF transformer

v.s. 

option 2:  raw data -> Ray Data -> HF transformer

We can discuss more in person next week.

[matthewdeng]

This is good content that I think everyone should read, regardless of whether or not they are starting with PyTorch data. Do you think we could bring this higher up in the guide (e.g. even in the introduction), and then reference it from here?

[woshiyyya]

OK. Sounds good to me.

[justinvyu]

High level comments:

1. Can we copy some content from this blog post? This user guide should be the place to compare Ray Data against other data ingest solutions. Particularly, I'm thinking of copying over the diagrams as well as the table comparing against torch dataloader, HF dataset, tf data, etc.
2. Proposed restructure of this guide:

(Ray Data + Ray Train) Quickstart
    -> Code examples, with the "Option 1: Ray Data" moved over here under each framework.
Why use Ray Data?
    -> Comparison with Other Data Ingest Solutions
        -> Comparison table
Alternative to Ray Data Ingest (Framework-native Dataloaders)
    -> "Ray Data is the recommended data loading solution for scalable blah blah blah, but Ray Train still integrates well with existing dataloading solutions you may be using, such as X, Y, Z.
    -> Link to the framework user guides, since we already go over how to set up the framework native dataloaders.
Ray Data Configurations
    -> all the remaining sections become subsections.

I think this structure fixes the problem where I was getting lost in the middle of the user guide because it suddenly starts talking about pytorch dataloader -- it wasn't clear that there are 2 separate paths: Ray Data vs. Alternatives. Now, we first put Ray Data front and center and make the case for it. Then, we talk about alternatives that are still integrated nicely.

3. For a follow-up PR, it would be nice to have some more realistic examples. For example, show read_parquet("s3://...") instead of the from_items dummy dataset that we have right now in the torch ray data quickstart. Can borrow this from the blog post again.

[woshiyyya]

Discussed with Angelina and below is a proposal of the user guide:

• Introduction (don’t need a title)
  • Layout the structure of the doc
  • Comparing framework-native utilities v.s. Ray Data, and guide user to choose one or the other.
    • Add quick link to the corresponding for "Use Framework-native .." and "Use Ray Data" sections
    • Show the benefits of ray data (can include contents in the blog post)
• Use Framework-native Data Utilities
  • Quickstart
    • Code snippets for Torch,Lighting, and HF
• Use Ray Data
  • Quickstart (add code snippets for each subsection)
    • Loading data
    • Inputting and splitting data
    • …
  • Remaining Ray Data Usage guide (Splitting Dataset, ..., Performance tips)

Main considerations:

1. Previously there are too many first level sections. The new proposal aims to make the user guide layout super clear -> Choose "Framework-native utilities" or Choose "Ray Data".
2. Do not mention Framework native utilities in the Ray Data section, and do not mention Ray Data in the Framework native utilities section.

Any thoughts? @matthewdeng @justinvyu @hongpeng-guo

[hongpeng-guo]

Discussed with Angelina and below is a proposal of the user guide:

• Introduction (don’t need a title)

  • Layout the structure of the doc

  • Comparing framework-native utilities v.s. Ray Data, and cuide user to choose one or the other.

    • Add quick link to the corresponding for "Use Framework-native .." and "Use Ray Data" sections
    • Show the benefits of ray data (can include contents in the blog post)

• Use Framework-native Data Utilities

  • Quickstart

    • Code snippets for Torch,Lighting, and HF

• Use Ray Data

  • Quickstart (add code snippets for each subsection)

    • Loading data
    • Inputting and splitting data
    • …

  • Remaining Ray Data Usage guide (Splitting Dataset, ..., Performance tips)

Main considerations:

1. Previously there are too many first level sections. The new proposal aims to make the user guide layout super clear -> Choose "Framework-native utilities" or Choose "Ray Data".
2. Do not mention Framework native utilities in the Ray Data section, and do not mention Ray Data in the Framework native utilities section.

Any thoughts? @matthewdeng @justinvyu @hongpeng-guo

I think the new proposal is very clear! Just one question whether we should put "Framework-native utilities` first, or "Ray data" first in this doc page.

[matthewdeng]

My preference would be to put Ray Data before the native ones. Though I do think it would be good either way to add a concise tip at the start of each section to point the user to the other section.

[woshiyyya]

@matthewdeng @hongpeng-guo ok, let's put "Ray Data" at first before the native ones, and cross link each other at the beginning of their section. I'll do it in the following PR.

[justinvyu]

Let's merge this one first!