Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: fix some grammar errors and refine some expressions #21

Merged
merged 2 commits into from
Dec 30, 2024

Conversation

caozhuozi
Copy link
Contributor

@caozhuozi caozhuozi commented Dec 23, 2024

In this PR, I've made the following changes:

  1. grammar fixes:

    • missing subject
      - If the model has multiple weight files, need to package them in separate layers. But recommended [...]
      + If the model has multiple weight files, they SHOULD be packaged in separate layers.
  2. removed the "The model specification needs to consider two factors" part.

    I don't think design considerations/motivations should be included in the specification document itself (but rather in a separate place such as README.md).

    I've transformed this information into a "Use Case" section, similar to the arrangement in the OCI Distribution Spec.

  3. reordered the "Workflow" and "Spec Definition" sections:

    I think it's better to introduce the spec itself before discussing the workflow.

  4. clarified the distinction between Model Format Spec and Manifest Spec:

    Several parts of the document blurred the distinction between these two concepts. For example,

    The model specification is defined through the artifact extension based on the OCI image specification, and extend model features through artifactType and annotations. Model storage and distribution can be optimized based on artifact extension.

    I attempted to explicitly differentiate them, as they represent concepts at different levels. For example,

    At a high level, the Model Format Specification is based on the OCI Image Format Specification and incorporates all its components. The key distinction lies in extending the OCI Image Manifest Specification to accommodate artifact usage specifically tailored for AI/ML models.

  5. removed redundancies:

    Several parts of the document repeat the same information, For example,

    • regarding artifactType and annotations properties:

      [...], and extends model features through artifactType and annotations. (in # Model Format Specification)

      [...], and extend model features through artifactType and annotations. (in ## Overview)

      Now only mentioned once:

      Specifically, it leverages the extensible artifactType and annotations properties to define attributes specific to model artifacts.

    • regarding compression:

      [...], it's recommended to use the application/vnd.oci.image.layer.v1.tar format for the model layer to avoid compression (in ### BUILD & PUSH)

      [...] But recommended package model weight files without compressed to avoid the container runtime decompressing the model layer (in ### Image Manifest Extension Properties)

      Now consolidated as an implementers note, aligning with the writing conventions used in the OCI Image Specification.

      Implementers note: It is recommended to package weight files without compression to avoid unnecessary overhead of decompression by the container runtime as model weight files are typically already compressed.

  6. added "REQUIRED" or "OPTIONAL" to all properties

    • Added "REQUIRED" to mediaType where it was missing.
    • Added "OPTIONAL" to annotations where it was missing.

@caozhuozi caozhuozi force-pushed the grammer-error branch 6 times, most recently from 0b93259 to 4645c6e Compare December 24, 2024 15:15
@caozhuozi caozhuozi changed the title [WIP] doc: fix some grammar error [WIP] doc: fix some grammar errors Dec 24, 2024
@caozhuozi caozhuozi changed the title [WIP] doc: fix some grammar errors [WIP] doc: fix some grammar errors and refine some expressions Dec 24, 2024
@caozhuozi caozhuozi force-pushed the grammer-error branch 8 times, most recently from 4af7f3c to 609b13f Compare December 27, 2024 02:51
@caozhuozi caozhuozi changed the title [WIP] doc: fix some grammar errors and refine some expressions doc: fix some grammar errors and refine some expressions Dec 27, 2024
bergwolf
bergwolf previously approved these changes Dec 27, 2024
Copy link
Contributor

@bergwolf bergwolf left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks! Please fix the lint error though.

Signed-off-by: caozhuozi <[email protected]>
Copy link
Contributor

@gaius-qi gaius-qi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@gaius-qi gaius-qi merged commit fe73e2e into CloudNativeAI:main Dec 30, 2024
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants