docs: fix critical findings from the docs deep review - #485
Merged
Conversation
Fixes the 10 critical findings from a read-only audit of docs.weaviate.io (/weaviate, /deploy, /cloud), plus five High-tier findings in the same files and one stale include that contradicted a section fixed here. Every claim was checked against Weaviate core or the official client source. Wrong information a reader would act on: - Both quickstarts told the reader to sign up for Cohere while every client snippet required an OpenAI key. Prose and the curl tabs now say OpenAI, matching the CI-executed snippets; Java and C# collection config switched to OpenAI to match. - google/generative marked gemini-2.5-flash as the default, but omitting the model makes the server fall back to a legacy PaLM model that the same page lists as deprecated. Marker removed, with a caution to set the model. - google/embeddings: the Gemini example failed server-side validation. Python passed a keyword the client rejects, Go named the wrong module, and the AI Studio examples omitted the Gemini endpoint, so collection creation failed with "projectId cannot be empty". - anthropic/generative had a default and model list frozen at July 2024. Default corrected; the hand-maintained list replaced with a link to the provider's model-names page, since the module has no allowlist. - search/similarity MMR examples used a parameter and factory that had both been renamed, so the snippets raised on use. All five call sites and the surrounding prose corrected. - OPERATIONAL_MODE documented values the parser does not accept, and an unrecognized value silently falls back to full read-write. Values corrected and the silent fallback documented. - The cluster-consensus troubleshooting answer was a verbatim copy of the unrelated async-replication answer. Rewritten around cluster membership and Raft. Corrected the case of ASYNC_REPLICATION_DISABLED. Snippets that could not run as printed: - typescript/notes-best-practices had pasted GitHub review UI text inside a JS block, making it a SyntaxError on copy-paste, plus invalid generic syntax. - read-all-objects used Go markers that appear twice in the source, so the snippet component spliced two regions together and leaked raw import lines into non-compiling Go. Unique markers added. Two further Go tabs referenced markers that do not exist and rendered as empty code boxes; those tabs are removed rather than left blank. - Removed a preview bullet claiming Python client support was unreleased. It has shipped, and that include renders into the MMR section corrected here. Enables tests/test_python.py::test_search_mmr. It was skipped on the stale grounds that MMR support was not in a released client; support has shipped, and the snippet runs green against a live instance using self-provided vectors, so it needs no provider credentials. The test now covers the corrected MMR examples in CI.
![orca-security-eu[bot]](https://avatars.githubusercontent.com/in/276244?s=60&v=4){kind=small}
There was a problem hiding this comment.
Orca Security Scan Summary
| Status | Check | Issues by priority | |
|---|---|---|---|
 Passed |
Infrastructure as Code |  0  0  0  0 |
View in Orca |
| Passed |
SAST | 0 0 0 0 |
View in Orca |
| Passed |
Secrets | 0 0 0 0 |
View in Orca |
| Passed |
Vulnerabilities | 0 0 0 0 |
View in Orca |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Weaviate docs and embedded code snippets to correct high-impact inaccuracies identified in a deep audit, aligning prose, configuration examples, and runnable snippets (plus tests) with current Weaviate/core-client behavior.
Changes:
- Align RAG/quickstart guidance and snippets to OpenAI (prose + curl + Java + C#), replacing Cohere-specific instructions where they contradicted CI-executed examples.
- Fix/refresh model-provider docs and snippet APIs (Google Gemini/Vertex vectorizer config, Anthropic model guidance, and MMR parameter/factory renames).
- Enable and exercise Python MMR snippet coverage in CI by un-skipping
test_search_mmr.
Reviewed changes
Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_python.py | Enables the Python MMR snippet test by removing the skip marker. |
| docs/weaviate/tutorials/quick-tour-of-weaviate.mdx | Updates prerequisites and header guidance from Cohere to OpenAI for the RAG step. |
| docs/weaviate/search/similarity.md | Updates MMR docs to the current diversity_selection + Diversity.mmr(...) API. |
| docs/weaviate/model-providers/google/generative.md | Removes “default” labeling and adds a caution to set the Gemini model explicitly. |
| docs/weaviate/model-providers/google/embeddings.md | Clarifies Google AI Studio requirements and client behavior regarding endpoints/project IDs. |
| docs/weaviate/model-providers/anthropic/generative.md | Replaces a stale hand-maintained model list with a default-model note + upstream link. |
| docs/weaviate/model-providers/_includes/provider.vectorizer.ts | Switches the TS Gemini vectorizer helper to the Gemini-specific configurator. |
| docs/weaviate/model-providers/_includes/provider.vectorizer.py | Fixes the Python Gemini vectorizer parameter name (model). |
| docs/weaviate/model-providers/_includes/provider.generative.ts | Updates Anthropic model examples to claude-haiku-4-5. |
| docs/weaviate/model-providers/_includes/provider.generative.py | Updates Anthropic model examples to claude-haiku-4-5. |
| docs/weaviate/manage-objects/read-all-objects.mdx | Fixes Go snippet markers and removes empty Go tabs where markers didn’t resolve. |
| docs/weaviate/client-libraries/typescript/notes-best-practices.mdx | Removes pasted UI text from a JS block and fixes invalid TS generic syntax. |
| docs/deploy/faqs/troubleshooting.md | Rewrites the cluster membership/consensus troubleshooting section and fixes env var casing. |
| docs/deploy/configuration/env-vars/index.md | Corrects OPERATIONAL_MODE documented values and warns about silent fallback behavior. |
| docs/cloud/quickstart.mdx | Updates Cohere → OpenAI prerequisites and header guidance for RAG. |
| _includes/feature-notes/v137-preview.mdx | Removes stale note about unreleased Python client support. |
| _includes/code/quickstart/quickstart.query.rag.mdx | Updates curl example to use OPENAI_API_KEY / X-OpenAI-Api-Key. |
| _includes/code/quickstart/quickstart.create_collection.mdx | Updates schema curl snippet module config to generative-openai. |
| _includes/code/java-v6/src/test/java/QuickstartTest.java | Switches Java quickstart generative module from Cohere to OpenAI. |
| _includes/code/howto/search.similarity.mmr.py | Updates the Python MMR snippet to the current API (diversity_selection, Diversity.mmr). |
| _includes/code/howto/go/docs/model-providers/2-usage-text/main.go | Fixes Google vectorizer module name and adds the Gemini endpoint in the Go schema example. |
| _includes/code/howto/go/docs/manage-data.read-all-objects_test.go | Introduces unique snippet markers for the Go “read all objects” example. |
| _includes/code/csharp/QuickstartTest.cs | Switches C# quickstart generative config from Cohere to OpenAI. |
Comments suppressed due to low confidence (1)
_includes/code/howto/go/docs/model-providers/2-usage-text/main.go:362
- This Vertex AI vectorizer config still uses snake_case keys (
project_id,model_id,api_endpoint) even though the docs on this page describeprojectId,modelId, andapiEndpoint. The comment also says "Vertex AU" (typo).
"text2vec-google": map[string]interface{}{
"properties": []string{"title"},
"project_id": "<google-cloud-project-id>", // Required for Vertex AU
"model_id": "textembedding-gecko@latest", // (Optional) To manually set the model ID
"api_endpoint": "<google-api-endpoint>", // (Optional) To manually set the API endpoint
},
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| #### Resolving the issue | ||
|
|
||
| Check your settings to check if you have asynchronous replication enabled. If `async_replication_disabled` is set to "true" then you'll need to set that variable to "false." Once it is enabled, the logs will show messages that indicate successful peers checks and synchronization for the nodes. | ||
| Check your settings to check if you have asynchronous replication enabled. If `ASYNC_REPLICATION_DISABLED` is set to "true" then you'll need to set that variable to "false." Once it is enabled, the logs will show messages that indicate successful peers checks and synchronization for the nodes. |
Comment on lines
323
to
327
| "text2vec-google": map[string]interface{}{ | ||
| "properties": []string{"title"}, | ||
| "model_id": "gemini-embedding-001", // (Optional) To manually set the model ID | ||
| "properties": []string{"title"}, | ||
| "apiEndpoint": "generativelanguage.googleapis.com", | ||
| "model_id": "gemini-embedding-001", // (Optional) To manually set the model ID | ||
| }, |
Addresses review feedback on this pull request. Weaviate matches module config keys by exact string, a plain map lookup with no case normalization and a silent fallback to the default on a miss. The snake_case keys these examples used were therefore ignored by the server: two of the three blocks failed collection creation with "projectId cannot be empty", and the model each example set was never applied. The accepted keys are apiEndpoint, projectId and modelId, which is also what this page's own parameter reference documents, so the snippets contradicted the prose beside them. Also corrects a "Vertex AU" typo, and rewrites a troubleshooting sentence that read "Check your settings to check ..." and referred to "peers checks".
g-despot
added a commit
that referenced
this pull request
Aug 1, 2026
llms.txt is hand-maintained in weaviate-io, but its code blocks must match the START/END regions of the snippets in this repo. The only enforcement was the weekly test_llms_txt_snippets_are_covered job, which fetches the live file. So PR #485/#487 moved the quickstart snippets to `data.ingest`, nothing here told the author that weaviate-io/static/llms.txt had to move too, and the break surfaced days later in a scheduled run. It is still red: 2 of 51 blocks. Add tests/check_llms_txt_drift.py, run by llms_txt_snippet_sync.yml on any PR touching a file that matches SNIPPET_GLOBS. It answers one question: once this PR merges, which llms.txt blocks would the weekly coverage test no longer find? It reuses that test's globs, regexes, _normalize and _load_llms_txt, so the two cannot disagree about what "matches" means. The check is advisory and always exits 0. When a snippet PR is opened, weaviate-io has not merged or deployed yet, so the live llms.txt legitimately cannot match; a blocking check would fail every honest PR and would be routinely overridden, which teaches people to ignore it. Findings are GitHub warning annotations on the changed marker lines plus a job summary carrying the exact block to paste into llms.txt. It stays quiet when there is nothing to do: weaviate-io shipped first and llms.txt already carries the new block, only scaffolding outside the markers changed, or a region moved or was renamed with its code intact. It degrades to a generic reminder, never a failure, if the base ref or llms.txt cannot be read. The path filter also covers the Java and C# snippets, which live with their language suites rather than under _includes/code/llms-txt/. llms_txt_tests.yml is untouched; the scheduled job behaves exactly as before.
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
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.
What's being changed:
Fixes the 10 critical findings from a read-only audit of
docs.weaviate.io(/weaviate,/deploy,/cloud), plus 5 High-tier findings that live in the same files, plus one stale include that contradicted a section fixed here.Every claim below was checked against Weaviate core or the official client source rather than against the existing docs.
Wrong information a reader would act on
model-providers/google/generativegemini-2.5-flashwas marked(default), but omitting the model makes the server fall back to a legacy PaLM model that this same page lists as deprecated. Marker removed, with a caution to always set the model explicitly.model-providers/google/embeddingsTypeError); Go named the wrong module (text2vec-awsinside the Google example); the TypeScript and Go AI Studio examples omitted the Gemini endpoint, so collection creation failed withprojectId cannot be empty.model-providers/anthropic/generativesearch/similaritydeploy/configuration/env-varsOPERATIONAL_MODEdocumented values that the parser does not accept. An unrecognized value silently falls back to full read-write, so an operator following this page to restrict a node got a fully writable one. Values corrected and the silent fallback documented.deploy/faqs/troubleshootingASYNC_REPLICATION_DISABLED, which has no effect lowercased.Snippets that could not run as printed
client-libraries/typescript/notes-best-practices— a line of pasted GitHub review UI text (Add commentMore actions) sat inside a JS block, making the snippet aSyntaxErroron copy-paste. Also fixed invalid generic syntax (get < Article > "Article").manage-objects/read-all-objects— the Go tab used markers that appear twice in the source, so the snippet component spliced two regions together and leaked raw import lines into non-compiling Go. Unique markers added. Two further Go tabs referenced markers that do not exist and rendered as empty code boxes; those tabs are removed rather than left blank._includes/feature-notes/v137-preview.mdx— removed a bullet claiming Python client support was unreleased. It has shipped, and this include renders directly into the MMR section corrected above, so it contradicted the working code beneath it.Test coverage
tests/test_python.py::test_search_mmris enabled by this PR. It was skipped on the stale grounds that MMR support was not yet in a released client. Support has shipped, and the snippet runs green against a live instance using self-provided vectors, so it needs no provider credentials. It now covers the corrected MMR examples, which is the fix most likely to regress silently.Type of change:
How has this been tested?
yarn startA full local build was not run. Stating that plainly rather than ticking the box. What was verified:
.md/.mdxcompiled with@mdx-js/mdxv3 and the result diffed againstmain: no new errors. The two files that fail compile in isolation fail identically onmain(they rely on the Docusaurus remark pipeline).FilteredTextBlockmarkers across the 13 modified pages resolve, each exactly once, with the extracted regions checked for balance. Verified by porting the component's own filter loop and rendering every block at both revisions, which is how the two empty Go tabs were confirmed empty onmaintoo.gofmt-clean. TypeScript/JS snippets parse.java-client 6.3.0viamvn -o test-compile;csharp-client 1.1.1via Roslyn). CI secrets need no change: both jobs already exportOPENAI_API_KEY.AttributeErrorto a clean run with its own assertions passing, and the Google AI Studio vectorizer payload goes fromHTTP 422 projectId cannot be emptytoHTTP 200.SkipLinktargets match the OpenAPI spec the site renders.Residual risk is therefore confined to whole-site build behavior that per-file compilation cannot surface. A
yarn buildin CI will close that gap.Known follow-ups, deliberately not in this PR
project_id,model_id,api_endpoint), but the server matches keys exactly in camelCase and silently drops unrecognized ones. So the Google "Vectorizer parameters" Go example is still non-functional even after the module-name fix here. This is a class of latent bug across the Go provider snippets and wants its own pass.CLUSTER_GOSSIP_BIND_PORT/CLUSTER_DATA_BIND_PORTdefaults are stated three different ways across three pages. The new troubleshooting section deliberately asserts no default port rather than pick one.docs/weaviate/model-providers/google/generative.mdstill says "The default model is used if no model is specified", now linking to a section that names no default.