docs(scheduler): document per-pod scoring weights by blackdragoon26 · Pull Request #759 · Project-HAMi/website

blackdragoon26 · 2026-08-11T13:15:46Z

What type of PR is this?
/kind documentation

What this PR does / why we need it:

Documents the per-Pod device-scoring weights introduced by Project-HAMi/HAMi#2469.

This update:

documents the hami.io/device-scoring-weights annotation
explains defaults and validation requirements
provides a complete Pod manifest
documents the weighted slot/core/memory formula
includes a checked example showing how weights affect device selection
clarifies interaction with binpack, spread, topology, mutex, capacity checks, and vendor-specific Fit behavior
updates the existing default GPU scoring examples to include virtual-device slot utilisation

This PR depends on Project-HAMi/HAMi#2469. The documented contract should be finalised together with that implementation.

Which issue(s) this PR fixes:

Fixes #758

I have not done the Chinese translation in this PR yet. This documents an unreleased feature in the English source-of-truth page, once I can get an initial review and green flag, I would update the the translation version as well in the PR

Checklist:

npm run lint and npm run format:check pass
npm run build succeeds for both en and zh
Chinese translation updated if English docs changed (or noted why not)
Commits are signed off (git commit -s)

AI Disclosure:
Codex was used to cross-check the implementation semantics and calculations, and to help draft the documentation. I reviewed and verified the final content and test results.

Summary by CodeRabbit

Documentation

Documented configurable GPU device-scoring weights for virtual-device slots, cores, and memory utilization.
Added annotation format, validation rules, default values, and scoring examples.
Clarified that invalid configurations prevent scheduling and that fit and topology constraints take precedence.
Updated GPU binpack and spread formulas to include virtual-device slot utilization.
Added corresponding guidance in both English and Chinese documentation.

Signed-off-by: blackdragoon26 <sankalp.jha9643@gmail.com>

hami-robot · 2026-08-11T13:15:50Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: blackdragoon26
Once this PR has been reviewed and has the lgtm label, please assign archlitchi for approval. For more information see the Kubernetes Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

netlify · 2026-08-11T13:15:53Z

✅ Deploy Preview for project-hami ready!

Name	Link
🔨 Latest commit	`9715d6e`
🔍 Latest deploy log	https://app.netlify.com/projects/project-hami/deploys/6a87363143cea10008ec126e
😎 Deploy Preview	https://deploy-preview-759--project-hami.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

hami-robot · 2026-08-11T13:15:56Z

Welcome @blackdragoon26! It looks like this is your first PR to Project-HAMi/website 🎉

coderabbitai · 2026-08-11T13:16:40Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 71d7b4a7-4ec8-434a-be93-3fcff5849615

📥 Commits

Reviewing files that changed from the base of the PR and between 11b09f9 and 9715d6e.

📒 Files selected for processing (3)

docs/userguide/configure.md
i18n/zh/docusaurus-plugin-content-docs/current/developers/scheduling.md
i18n/zh/docusaurus-plugin-content-docs/current/userguide/configure.md

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

Walkthrough

The documentation adds the hami.io/device-scoring-weights annotation for slot, core, and memory utilization. It defines validation, defaults, scoring behavior, and unchanged constraints. GPU binpack and spread examples now include virtual-device slot utilization in English and Chinese guides.

Changes

GPU scoring documentation

Layer / File(s)	Summary
Scoring contract and policy formulas `docs/developers/scheduling.md`, `docs/userguide/configure.md`, `i18n/zh/docusaurus-plugin-content-docs/current/developers/scheduling.md`, `i18n/zh/docusaurus-plugin-content-docs/current/userguide/configure.md`	Documents the annotation format, validation rules, defaults, weighted scoring, and unchanged scheduling constraints. Updates binpack and spread formulas and examples to include virtual-device slot utilization.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk: ⚪ Minimal · up to 9715d

This documentation update does not introduce an actionable merge-blocking risk and is merge-ready after normal checks and review.

Suggested reviewers: mesutoezdil

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The documentation covers the requested annotation, validation, formulas, policies, constraints, examples, and translation, but states the wrong default memory weight.	Correct the documented default from slot=1,core=1,memory=3 to slot=1,core=1,memory=1, unless the implementation or issue requirements are updated.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation change for per-Pod scheduler scoring weights.
Out of Scope Changes check	✅ Passed	The changes remain within the linked issue's documentation scope, including user-guide placement and Chinese translation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

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.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

FouoF

The doc seem placing incorrect. This is a user-face change so it should update or draft a user guide instead of developer doc. Also better add a Chinese version.

blackdragoon26 · 2026-08-13T09:33:53Z

The doc seem placing incorrect. This is a user-face change so it should update or draft a user guide instead of developer doc. Also better add a Chinese version.

Thanks for the review.
my bad on that part, I will do fixing on it quickly.

blackdragoon26 · 2026-08-13T10:23:59Z

@FouoF , sorry to ping you again
I am bit confused that since HAMi#2469 implements this in the generic device-scoring path,
So should I create a general user-guide page, or
add it to the existing NVIDIA scheduling-policy page because the example uses NVIDIA resources?
Honestly, I am leaning toward a general page to avoid implying the feature is NVIDIA-only.

blackdragoon26 · 2026-08-17T09:36:30Z

@FouoF , sorry to ping you again I am bit confused that since HAMi#2469 implements this in the generic device-scoring path, So should I create a general user-guide page, or add it to the existing NVIDIA scheduling-policy page because the example uses NVIDIA resources? Honestly, I am leaning toward a general page to avoid implying the feature is NVIDIA-only.

Re-pinging for the same

blackdragoon26 · 2026-08-19T10:46:39Z

@FouoF @rootsongjc @windsonsea @fishman
Sorry to disturb you maintainers,
I just wanted to bring this issue in your pings again,
Since technical PR has been merged, I just felt the urgency to get Docs PR merged for this as well.

Regards

@FouoF , sorry to ping you again I am bit confused that since HAMi#2469 implements this in the generic device-scoring path, So should I create a general user-guide page, or add it to the existing NVIDIA scheduling-policy page because the example uses NVIDIA resources? Honestly, I am leaning toward a general page to avoid implying the feature is NVIDIA-only.

mesutoezdil

checked all four worked examples, the math is right. upstream hami 2469 merged on aug 17, so this can move forward, please add the promised zh translation. small note: the checklist marks the zh box even though the body says it is deferred.

mesutoezdil · 2026-08-20T16:13:19Z

+HAMi predicts each candidate device's utilization after placing the request, then calculates its device score as follows:
+
+```text
+score = 10 * (


does the implementation normalize by the weight sum? if it divides by slot+core+memory these example numbers change. worth confirming against the merged code.

I did re-check on the merged implementation of mine.
yes ComputeScore directly adds the weighted slot, core, and memory terms without dividing by the weight sum: source.
Also, the merged test confirms the documented 26 and 27 scores for slot=1,core=1,memory=3: test.
So I feel, that I should keep the example calculations unchanged.

mesutoezdil · 2026-08-20T16:13:19Z

+metadata:
+  name: memory-weighted-gpu-pod
+  annotations:
+    hami.io/device-scoring-weights: "slot=1,core=1,memory=3"


also list this annotation in the pod annotations table in userguide/configure.md, that is where users look first.

mesutoezdil · 2026-08-20T16:13:19Z


 ```text
-score: ((request.core + used.core) / allocatable.core + (request.mem + used.mem) / allocatable.mem)) * 10
+score: ((request.slot + used.slot) / allocatable.slot +


the slot term is new from 2469, right? released versions score core and memory only. since this page is next docs it is fine, just confirm the base formula change is part of the same pr.

Checked the code before the merge of #2469, and the slot term was already there as usedScore source.
Thus, No, the #2469 only made its weight configurable, it did not add the slot term.
So, I think that I should keep the three-term formula as is.

blackdragoon26 · 2026-08-20T17:02:51Z

checked all four worked examples, the math is right. upstream hami 2469 merged on aug 17, so this can move forward, please add the promised zh translation. small note: the checklist marks the zh box even though the body says it is deferred.

Thanks for review, I will add zsh translation.
About the checklist, I intentionally ticked the box since I explained the "why not added" part in the description, hence thought, that should work.
Please do correct me, if this was not the right approach.
Regards

Signed-off-by: blackdragoon26 <sankalp.jha9643@gmail.com>

The snapshot was cut before the v2.10 feature documentation PRs (Project-HAMi#794, Project-HAMi#734, Project-HAMi#759, Project-HAMi#775) merged, so it described v2.9 behavior for flagship features. Keep only the changelog and the homepage release badge for now; re-cut the snapshot once those PRs land. Signed-off-by: Jimmy Song <jimmy@dynamia.ai>

docs(scheduler): document per-pod scoring weights

11b09f9

Signed-off-by: blackdragoon26 <sankalp.jha9643@gmail.com>

hami-robot Bot added kind/documentation Improvements or additions to documentation dco-signoff: yes labels Aug 11, 2026

hami-robot Bot requested a review from rootsongjc August 11, 2026 13:15

hami-robot Bot requested a review from windsonsea August 11, 2026 13:15

hami-robot Bot added the size/M label Aug 11, 2026

github-actions Bot added the area/docs label Aug 11, 2026

FouoF reviewed Aug 13, 2026

View reviewed changes

mesutoezdil reviewed Aug 20, 2026

View reviewed changes

docs(scheduler): add scoring weights references

9715d6e

Signed-off-by: blackdragoon26 <sankalp.jha9643@gmail.com>

github-actions Bot added the area/i18n label Aug 20, 2026

mesutoezdil mentioned this pull request Aug 21, 2026

feat(versions): release HAMi v2.10.0 #812

Open

4 tasks

Uh oh!

Conversation

blackdragoon26 commented Aug 11, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Documentation

Uh oh!

hami-robot Bot commented Aug 11, 2026

Uh oh!

netlify Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for project-hami ready!

Uh oh!

hami-robot Bot commented Aug 11, 2026

Uh oh!

coderabbitai Bot commented Aug 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

❌ Failed checks (1 warning)

Uh oh!

FouoF left a comment

Choose a reason for hiding this comment

Uh oh!

blackdragoon26 commented Aug 13, 2026

Uh oh!

blackdragoon26 commented Aug 13, 2026

Uh oh!

blackdragoon26 commented Aug 17, 2026

Uh oh!

blackdragoon26 commented Aug 19, 2026

Uh oh!

mesutoezdil left a comment

Choose a reason for hiding this comment

Uh oh!

mesutoezdil Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

blackdragoon26 Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

mesutoezdil Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

blackdragoon26 Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

mesutoezdil Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

blackdragoon26 Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

blackdragoon26 commented Aug 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

blackdragoon26 commented Aug 11, 2026 •

edited by coderabbitai Bot

Loading

netlify Bot commented Aug 11, 2026 •

edited

Loading

coderabbitai Bot commented Aug 11, 2026 •

edited

Loading