From ea984cf3ea8359edb1f45089c063316fe9be8bd0 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Mon, 13 Jul 2026 23:01:36 +0000 Subject: [PATCH] docs: add watsonx.ai reranker integration page --- docs/docs.json | 3 +- docs/integrations/reranking/watsonx.mdx | 64 +++++++++++++++++++++++++ docs/reranking/index.mdx | 3 +- docs/snippets/integrations.mdx | 2 + 4 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 docs/integrations/reranking/watsonx.mdx diff --git a/docs/docs.json b/docs/docs.json index e1e3d32a..3e513437 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -266,7 +266,8 @@ "integrations/reranking/colbert", "integrations/reranking/jina", "integrations/reranking/openai", - "integrations/reranking/voyageai" + "integrations/reranking/voyageai", + "integrations/reranking/watsonx" ] }, { diff --git a/docs/integrations/reranking/watsonx.mdx b/docs/integrations/reranking/watsonx.mdx new file mode 100644 index 00000000..5949f7fd --- /dev/null +++ b/docs/integrations/reranking/watsonx.mdx @@ -0,0 +1,64 @@ +--- +title: Watsonx Reranker +sidebarTitle: "IBM watsonx.ai" +description: Rerank LanceDB search results with the IBM watsonx.ai text rerank API. Supports vector, FTS, and hybrid search with configurable models, projects, and spaces. + +--- + +import { PyRerankingWatsonxUsage } from '/snippets/integrations.mdx'; + +# Watsonx Reranker + +This reranker uses the [IBM watsonx.ai](https://cloud.ibm.com/docs/apis/watsonx-ai#text-rerank) text rerank API to reorder search results. Pass `WatsonxReranker()` to the `rerank()` method on a query. Credentials come from the `WATSONX_API_KEY` and `WATSONX_PROJECT_ID` (or `WATSONX_SPACE_ID`) environment variables, or can be passed explicitly as arguments. + +> **Note:** Supported query types – Hybrid, Vector, and FTS. + +```shell +pip install ibm-watsonx-ai +``` + + + + {PyRerankingWatsonxUsage} + + + +Accepted Arguments +---------------- +| Argument | Type | Default | Description | +| --- | --- | --- | --- | +| `model_name` | `str` | `"cross-encoder/ms-marco-minilm-l-12-v2"` | The rerank model ID. See [supported rerank models](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-models-embed.html?context=wx#rerank). | +| `column` | `str` | `"text"` | The name of the table column to use as document input. | +| `top_n` | `int` | `None` | The number of results to return. If `None`, all results are returned. | +| `return_score` | `str` | `"relevance"` | Options are `"relevance"` or `"all"`. Controls which score columns are kept on the result. | +| `api_key` | `str` | `None` | IBM Cloud API key. Falls back to the `WATSONX_API_KEY` environment variable. | +| `project_id` | `str` | `None` | watsonx.ai project ID. Falls back to `WATSONX_PROJECT_ID`. Mutually exclusive with `space_id`. | +| `space_id` | `str` | `None` | watsonx.ai deployment space ID. Falls back to `WATSONX_SPACE_ID`. Mutually exclusive with `project_id`. | +| `url` | `str` | `"https://us-south.ml.cloud.ibm.com"` | watsonx.ai service URL. | +| `truncate_input_tokens` | `int` | `None` | Truncate each document to this many tokens before scoring. | + + +You must supply exactly one of `project_id` or `space_id` (either as an argument or via its environment variable). Setting both, or neither, raises a `ValueError`. + + +## Supported scores for each query type + +You can specify the type of scores you want the reranker to return. The following are the supported scores for each query type: + +### Hybrid Search +|`return_score`| Status | Description | +| --- | --- | --- | +| `relevance` | ✅ Supported | Results only have the `_relevance_score` column. | +| `all` | ❌ Not Supported | Results have vector(`_distance`) and FTS(`score`) along with Hybrid Search score(`_relevance_score`). | + +### Vector Search +|`return_score`| Status | Description | +| --- | --- | --- | +| `relevance` | ✅ Supported | Results only have the `_relevance_score` column. | +| `all` | ✅ Supported | Results have vector(`_distance`) along with Hybrid Search score(`_relevance_score`). | + +### FTS Search +|`return_score`| Status | Description | +| --- | --- | --- | +| `relevance` | ✅ Supported | Results only have the `_relevance_score` column. | +| `all` | ✅ Supported | Results have FTS(`score`) along with Hybrid Search score(`_relevance_score`). | diff --git a/docs/reranking/index.mdx b/docs/reranking/index.mdx index d8003739..722fe2b1 100644 --- a/docs/reranking/index.mdx +++ b/docs/reranking/index.mdx @@ -69,9 +69,10 @@ providers that need an API key live under [integrations](/integrations/reranking | `JinaReranker` | `jina-reranker-v2-base-multilingual` | | `OpenaiReranker` | `gpt-4-turbo-preview` | | `VoyageAIReranker` | No default (model name required) | +| `WatsonxReranker` | `cross-encoder/ms-marco-minilm-l-12-v2`| The model-based rerankers need their provider package installed, and the hosted ones -(`CohereReranker`, `JinaReranker`, `OpenaiReranker`, `VoyageAIReranker`) also need an API key, passed +(`CohereReranker`, `JinaReranker`, `OpenaiReranker`, `VoyageAIReranker`, `WatsonxReranker`) also need an API key, passed as an `api_key` argument or set in the provider-specific environment variable. Rerankers add `_relevance_score` and return rows ordered by descending relevance. Python rerankers diff --git a/docs/snippets/integrations.mdx b/docs/snippets/integrations.mdx index 645618b7..de11f10a 100644 --- a/docs/snippets/integrations.mdx +++ b/docs/snippets/integrations.mdx @@ -172,6 +172,8 @@ export const PyRerankingRrfUsage = "import lancedb\nfrom lancedb.embeddings impo export const PyRerankingVoyageaiUsage = "import os\n\nimport lancedb\nfrom lancedb.embeddings import get_registry\nfrom lancedb.pydantic import LanceModel, Vector\nfrom lancedb.rerankers import VoyageAIReranker\n\nembedder = get_registry().get(\"sentence-transformers\").create()\ndb = lancedb.connect(\"~/.lancedb\")\n\nclass Schema(LanceModel):\n text: str = embedder.SourceField()\n vector: Vector(embedder.ndims()) = embedder.VectorField()\n\ndata = [\n {\"text\": \"hello world\"},\n {\"text\": \"goodbye world\"},\n]\ntbl = db.create_table(\"test\", schema=Schema, mode=\"overwrite\")\ntbl.add(data)\nreranker = VoyageAIReranker(model_name=\"rerank-2\")\n\n# Run vector search with a reranker\nresult = tbl.search(\"hello\").rerank(reranker=reranker).to_list()\n\n# Run FTS search with a reranker\nresult = tbl.search(\"hello\", query_type=\"fts\").rerank(reranker=reranker).to_list()\n\n# Run hybrid search with a reranker\ntbl.create_fts_index(\"text\", replace=True)\nresult = (\n tbl.search(\"hello\", query_type=\"hybrid\").rerank(reranker=reranker).to_list()\n)\n"; +export const PyRerankingWatsonxUsage = "import os\n\nimport lancedb\nfrom lancedb.embeddings import get_registry\nfrom lancedb.pydantic import LanceModel, Vector\nfrom lancedb.rerankers import WatsonxReranker\n\nembedder = get_registry().get(\"sentence-transformers\").create()\ndb = lancedb.connect(\"~/.lancedb\")\n\nclass Schema(LanceModel):\n text: str = embedder.SourceField()\n vector: Vector(embedder.ndims()) = embedder.VectorField()\n\ndata = [\n {\"text\": \"hello world\"},\n {\"text\": \"goodbye world\"},\n]\ntbl = db.create_table(\"test\", schema=Schema, mode=\"overwrite\")\ntbl.add(data)\n\n# Credentials pulled from WATSONX_API_KEY and WATSONX_PROJECT_ID (or WATSONX_SPACE_ID)\nreranker = WatsonxReranker(\n api_key=os.environ[\"WATSONX_API_KEY\"],\n project_id=os.environ[\"WATSONX_PROJECT_ID\"],\n)\n\n# Run vector search with a reranker\nresult = tbl.search(\"hello\").rerank(reranker=reranker).to_list()\n\n# Run FTS search with a reranker\nresult = tbl.search(\"hello\", query_type=\"fts\").rerank(reranker=reranker).to_list()\n\n# Run hybrid search with a reranker\ntbl.create_fts_index(\"text\", replace=True)\nresult = (\n tbl.search(\"hello\", query_type=\"hybrid\").rerank(reranker=reranker).to_list()\n)\n"; + export const TsFrameworksGenkitCustomIndexer = "export const menuPdfIndexer = lancedbIndexerRef({\n // Using all defaults, for dbUri, tableName, and embedder, etc\n});\n\nconst chunkingConfig = {\n minLength: 1000,\n maxLength: 2000,\n splitter: \"sentence\",\n overlap: 100,\n delimiters: \"\",\n} as any;\n\nasync function extractTextFromPdf(filePath: string) {\n const pdfFile = path.resolve(filePath);\n const dataBuffer = await readFile(pdfFile);\n const data = await pdf(dataBuffer);\n return data.text;\n}\n\nexport const indexMenu = ai.defineFlow(\n {\n name: \"indexMenu\",\n inputSchema: z.string().describe(\"PDF file path\"),\n outputSchema: z.void(),\n },\n async (filePath: string) => {\n filePath = path.resolve(filePath);\n\n // Read the pdf.\n const pdfTxt = await ai.run(\"extract-text\", () => extractTextFromPdf(filePath));\n\n // Divide the pdf text into segments.\n const chunks = await ai.run(\"chunk-it\", async () => chunk(pdfTxt, chunkingConfig));\n\n // Convert chunks of text into documents to store in the index.\n const documents = chunks.map((text) => {\n return Document.fromText(text, { filePath });\n });\n\n // Add documents to the index.\n await ai.index({\n indexer: menuPdfIndexer,\n documents,\n options: {\n writeMode: WriteMode.Overwrite,\n } as any,\n });\n },\n);\n"; export const TsFrameworksGenkitCustomRetriever = "export const menuRetriever = lancedbRetrieverRef({\n tableName: \"table\", // Use the same table name as the indexer.\n displayName: \"Menu\", // Use a custom display name.\n});\n\nexport const menuQAFlow = ai.defineFlow(\n { name: \"Menu\", inputSchema: z.string(), outputSchema: z.string() },\n async (input: string) => {\n // retrieve relevant documents\n const docs = await ai.retrieve({\n retriever: menuRetriever,\n query: input,\n options: {\n k: 3,\n },\n });\n\n const extractedContent = docs.map((doc) => {\n if (doc.content && Array.isArray(doc.content) && doc.content.length > 0) {\n if (doc.content[0].media && doc.content[0].media.url) {\n return doc.content[0].media.url;\n }\n }\n return \"No content found\";\n });\n\n console.log(\"Extracted content:\", extractedContent);\n\n const { text } = await ai.generate({\n model: gemini(\"gemini-2.0-flash\"),\n prompt: `\nYou are acting as a helpful AI assistant that can answer \nquestions about the food available on the menu at Genkit Grub Pub.\n\nUse only the context provided to answer the question.\nIf you don't know, do not make up an answer.\nDo not add or change items on the menu.\n\nContext:\n${extractedContent.join(\"\\n\\n\")}\n\nQuestion: ${input}`,\n docs,\n });\n\n return text;\n },\n);\n";