readme: docker-first quickstart, fix dead links, typography cleanup#176
Open
fm1320 wants to merge 10 commits into
Open
readme: docker-first quickstart, fix dead links, typography cleanup#176fm1320 wants to merge 10 commits into
fm1320 wants to merge 10 commits into
Conversation
- Quickstart leads with docker run; remove pip install sie-server - Fix npm package name to @superlinked/sie-sdk - Repoint docs links from sie.dev to superlinked.com - Replace dead reference/models page with superlinked.com/models - Footer now superlinked.com/docs - Remove em dashes from Explore section
fm1320
changed the title
- One-sentence framing of the server+SDK architecture at top of Quickstart - Steps renamed: "Run the engine" / "Call it from Python" - Note image sizes (~1 GB CPU, ~9 GB GPU) and first-model-load time - Note SDK is a thin HTTP client, not a model runtime
- Remove the Colab badge line above step 1 (notebook still linked in Explore) - Reframe quickstart: explicitly tell readers to start docker first, then SDK - Rename step 2 from 'Call it from Python' to language-neutral 'Call it' - Mount a named docker volume for the HF cache so model weights persist across runs; chose named volume over host bind-mount because the container runs as non-root sie user and bind-mounts hit UID issues on macOS/Windows - Replace the 'ready in seconds' claim with a measured statement: container reaches /readyz in a few seconds; verified at 5.3s on Apple Silicon under Rosetta against ghcr.io/superlinked/sie-server:latest-cpu-default - Verified end to end: encode(Stella 400M, Hello world) -> shape (1024,); warm call returns in ~0.1s - Note --platform linux/amd64 requirement for Apple Silicon
- Step 2 was 'Call it', too generic; rename to call out both supported SDKs - Show pip and pnpm install commands side by side in step 2 - Trim the redundant TypeScript line below the Python example to a pointer at the TS docs
…code The dense post-docker paragraph was a wall of caveats that buried the hook. Keep only the one-liner that unblocks pull on Apple Silicon and the link to the deployment guide. Move the 'first model call is slow' note under the code example, where a dev would actually hit it.
The 'Apple Silicon: add --platform linux/amd64' footnote was easy to miss; most local dev happens on Mac, so the macOS line is now first-class and the --platform flag is baked into the command itself. Verified all three lines: - macOS (Apple Silicon): /readyz 200 after 6s under Rosetta - Linux CPU: same image, same command without --platform - Linux GPU: --gpus all on the cuda12 image Footer now links to the Superlinked talk at the AI Engineer conference.
The Rosetta/platform explanation was for chat, not docs. The flag is in the command line; that is enough for a dev trying things out quickly. Footer link reframed from 'Watch the AI Engineer talk' to 'Why we built SIE (AI Engineer Europe 2026)' so the reason to click is the motivation story, not the format.
1. Cut the framing paragraph from three sentences to one 2. Move 'first call is slow' note from below the code into the code itself, right where a dev will be staring at the call 3. Swap the example to small models so first run is ~40s instead of ~10 min: - encode: all-MiniLM-L6-v2 (~90 MB, 384-dim) - score: ms-marco MiniLM L-6 (~80 MB) - extract: GLiNER multi v2.1 (unchanged) Verified live: encode -> shape (384,), elapsed 40s on Apple Silicon under Rosetta; warm calls in ms. 4. Add 'curl /readyz' sanity-check between Step 1 and Step 2 5. Drop the redundant 'three functions' bullet from About 6. Helm placeholder <TOKEN> -> YOUR_HF_TOKEN 7. Bridge from Explore catalog display names to HF IDs used in the SDK
… outputs
- Move 'Why we built SIE' from footer up into the Explore section, alongside
Notebooks and Examples. Footer is a footnote and a CTA does not belong there.
- Drop the 'See the deployment guide for GPU pinning, read-only filesystems,
and tuning' line. None of those are local-dev concerns; the deployment
guide is still linked from the Production section where it belongs.
- Fix example output values to match what the models actually return,
verified end-to-end against ghcr.io/superlinked/sie-server:latest-cpu-default:
* encode(all-MiniLM-L6-v2): shape (384,)
* score(ms-marco-MiniLM-L-6-v2): logits -7.1 / -11.048 (not 0.998/0.012;
cross-encoder outputs raw logits, not probabilities)
* extract(gliner_multi-v2.1): Tim Cook=0.991, Apple=0.978
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docker runand drops thepip install sie-serverpath. Docker is the canonical local path; the pip route added env friction without paying for itself.http://localhost:8080, which is what the docker command exposes).@sie/sdk->@superlinked/sie-sdk(the published name inpackages/sie_ts_sdk/package.json). The old command 404s.sie.dev/docs/...tosuperlinked.com/docs/....sie.devis now a 308 redirect shim; use the canonical domain.sie.dev/docs/reference/models/was already 404 (pre-existing dead link). Replaced withhttps://superlinked.com/models, the actual 85+ model catalog page.superlinked.com/docs.->arrows on link text. Nav and footer use|, prose lists use commas, link-pair lines use periods.Verification
packages/sie_sdk/src/sie_sdk/client/sync.py:encode(model, Item)returnsEncodeResult["dense"]score(model, query, [items])returnsScoreResult["scores"]extract(model, Item, labels=[...])returnsExtractResult["entities"]latest-cpu-defaultandlatest-cuda12-defaultconfirmed live on GHCR.Test plan
docker run -p 8080:8080 ghcr.io/superlinked/sie-server:latest-cpu-defaultboots