docs: overhaul README for clarity, add problem statement and quick start guide - #2086
docs: overhaul README for clarity, add problem statement and quick start guide#2086fishman wants to merge 2 commits into
Conversation
hami-robot
Bot
added
kind/documentation
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: fishman The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThe README updates product messaging, documents the device virtualization flow, and expands quick-start instructions with HAMi readiness checks and in-container GPU memory verification. ChangesHAMi README updates
Estimated code review effort: 1 (Trivial) | ~5 minutes Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the README.md to improve the project's overview, restructure the introduction into clearer problem and solution sections, and expand the installation and verification guides with practical commands. The review feedback points out a syntax error in the markdown link for the 'Contributing' document, which uses a double opening bracket.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
5f435c5 to
89d1db6
Compare
89d1db6 to
874b922
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 21: Qualify the README’s GPU memory/compute isolation and exact-memory
examples at the introductory description and referenced sections to apply only
to the default NVIDIA configuration, or describe them as requested/configured
values. Align these statements with the backend capability caveat and avoid
presenting values such as 3000 or exactly 3GB as universal guarantees.
- Around line 130-140: Update the README verification guidance around the
scheduler and device plugin to avoid implying exactly two HAMI pods are
required. State that the scheduler must be Running and the device-plugin pod or
pods on GPU nodes must be Running, without assuming a fixed pod count.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Line 23: Correct the malformed Contributing link in the README navigation by
removing the stray extra opening bracket, while preserving its existing
CONTRIBUTING.md target and surrounding links.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
b1c0825 to
8f8f2f0
Compare
…art guide Improve the CTA structure by keeping it at the top with a clear problem statement to increase conversion rates. Signed-off-by: Reza Jelveh <fishmangit@dynamia.ai>
…on't know HAMi Signed-off-by: Reza Jelveh <fishmangit@dynamia.ai>
|  | ||
| HAMi (Heterogeneous AI Computing Virtualization Middleware) lets you share GPUs across Kubernetes workloads with memory and compute isolation, without changing application code. Formerly k8s-vGPU-scheduler. | ||
|
|
||
| [Docs](https://docs.project-hami.io) | [Quick Start](#quick-start) | [Discord](https://discord.gg/Amhy7XmbNq) | [Issues](https://github.com/Project-HAMi/HAMi/issues) | [Contributing](CONTRIBUTING.md) |
There was a problem hiding this comment.
docs.project-hami.io does not resolve, this link should point to https://project-hami.io/docs/ instead
| -> Mutating webhook (inject device request) | ||
| -> Scheduler (select GPU and node) | ||
| -> Device plugin (allocate GPU memory/cores) | ||
| -> Container runtime (inject HAMi driver) |
There was a problem hiding this comment.
the container runtime does not inject anything here, it is the device plugin's allocate that mounts libvgpu.so into the container, so this should read device plugin (inject libvgpu.so) instead
There was a problem hiding this comment.
the container runtime does not inject anything here, it is the device plugin's allocate that mounts libvgpu.so into the container, so this should read device plugin (inject libvgpu.so) instead
@mesutoezdil AFAIK, the device plugin tells the container runtime to inject lib with ContainerAllocateResponse
There was a problem hiding this comment.
@fishman I think we should replace "HAMi driver" with "HAMi-Core lib"
There was a problem hiding this comment.
the container runtime does not inject anything here, it is the device plugin's allocate that mounts libvgpu.so into the container, so this should read device plugin (inject libvgpu.so) instead
@mesutoezdil AFAIK, the device plugin tells the container runtime to inject lib with
ContainerAllocateResponse
right, but the runtime only executes a generic mount the device plugin requested, so the stage label belongs to the device plugin
There was a problem hiding this comment.
awesome, thank you for reviewing this
| limits: | ||
| nvidia.com/gpu: 1 | ||
| nvidia.com/gpumem: 3000 | ||
| nvidia.com/gpumem: 3000 # 3GB of 40GB |
There was a problem hiding this comment.
nvidia.com/gpumem: 3000 is 3000 mib, not exactly 3gb, so this comment should say approximately 3gb or just drop the conversion
| ``` | ||
|
|
||
| The workload sees the allocated device resources inside the container, while HAMi coordinates scheduling, allocation, and isolation. | ||
| Inside the container, CUDA sees exactly 3GB - not 40GB. HAMi enforces this at the driver level. |
There was a problem hiding this comment.
3000 mib is about 2.93 gib, not exactly 3gb, so this should say approximately 3gb instead of exactly 3gb
| ``` | ||
|
|
||
| The workload sees the allocated device resources inside the container, while HAMi coordinates scheduling, allocation, and isolation. | ||
| Inside the container, CUDA sees exactly 3GB - not 40GB. HAMi enforces this at the driver level. |
There was a problem hiding this comment.
hami enforces this through its userspace interception library, libvgpu.so, not at the driver level
| The workload sees the allocated device resources inside the container, while HAMi coordinates scheduling, allocation, and isolation. | ||
| Inside the container, CUDA sees exactly 3GB - not 40GB. HAMi enforces this at the driver level. | ||
|
|
||
| **Memory isolation**: Hard limit. A pod requesting 3GB cannot exceed 3GB, even if memory is available. |
There was a problem hiding this comment.
3gb here is again 3000 mib, not an exact value, so consider wording this as approximately 3gb too
| Check what the workload sees inside the container: | ||
| ```bash | ||
| kubectl exec gpu-pod -- nvidia-smi | ||
| # Output shows only 3GB of GPU memory (not the full 40GB) |
There was a problem hiding this comment.
the container shows 3000 mib here, not exactly 3gb, so this comment should say approximately 3gb as well
8f8f2f0 to
9b461c8
Compare
3 participants
Improve the CTA structure by keeping it at the top with a clear problem
statement to increase conversion rates.
Signed-off-by: Reza Jelveh fishmangit@dynamia.ai
What type of PR is this?
/kind documentation
What this PR does / why we need it:
Improve the CTA structure by keeping it at the top with a clear problem
statement to increase conversion rates.
Does this PR introduce a user-facing change?:
It changes the first thing people see when engaging with the project on github
Summary by CodeRabbit
nvidia-smivalidation to confirm reduced visible GPU memory for the requested fraction.