WatsonxRerank

Reference docs

This page contains reference documentation for WatsonxRerank. See the docs for conceptual guides, tutorials, and examples on using WatsonxRerank.

langchain_ibm.rerank.WatsonxRerank

Bases: BaseDocumentCompressor

Document compressor that uses watsonx Rerank API.

Setup

To use, you should have langchain_ibm python package installed, and the environment variable WATSONX_API_KEY set with your API key, or pass it as a named parameter api_key to the constructor.

pip install -U langchain-ibm

# or using uv
uv add langchain-ibm

export WATSONX_API_KEY="your-api-key"

Deprecated

apikey and WATSONX_APIKEY are deprecated and will be removed in version 2.0.0. Use api_key and WATSONX_API_KEY instead.

Instantiate

from langchain_ibm import WatsonxRerank
from ibm_watsonx_ai.foundation_models.schema import RerankParameters

parameters = RerankParameters(truncate_input_tokens=20)

ranker = WatsonxRerank(
    model_id="cross-encoder/ms-marco-minilm-l-12-v2",
    url="https://us-south.ml.cloud.ibm.com",
    project_id="*****",
    params=parameters,
    # api_key="*****"
)

Rerank

query = "red cat chasing a laser pointer"
documents = [
    "A red cat darts across the living room, pouncing on a red laser dot.",
    "Two dogs play fetch in the park with a tennis ball.",
    "The tabby cat naps on a sunny windowsill all afternoon.",
    "A recipe for tuna casserole with crispy breadcrumbs.",
]

ranker.rerank(documents=documents, query=query)

[
    {"index": 0, "relevance_score": 0.8719543218612671},
    {"index": 2, "relevance_score": 0.6520894169807434},
    {"index": 1, "relevance_score": 0.6270776391029358},
    {"index": 3, "relevance_score": 0.4607713520526886},
]

METHOD	DESCRIPTION
validate_environment	Validate that credentials and python package exists in environment.
rerank	Rerank documents.
compress_documents	Compress documents using watsonx's rerank API.
acompress_documents	Async compress retrieved documents given the query context.

model_id instance-attribute

model_id: str

Type of model to use.

project_id class-attribute instance-attribute

project_id: str | None = None

ID of the Watson Studio project.

space_id class-attribute instance-attribute

space_id: str | None = None

ID of the Watson Studio space.

url class-attribute instance-attribute

url: SecretStr = Field(
    alias="url", default_factory=secret_from_env("WATSONX_URL", default=None)
)

URL to the Watson Machine Learning or CPD instance.

api_key class-attribute instance-attribute

api_key: SecretStr | None = Field(
    default_factory=secret_from_env_multi(
        names_priority=["WATSONX_API_KEY", "WATSONX_APIKEY"],
        deprecated={"WATSONX_APIKEY"},
    ),
    serialization_alias="api_key",
    validation_alias=AliasChoices("api_key", "apikey"),
    description="API key to the Watson Machine Learning or CPD instance.",
)

API key to the Watson Machine Learning or CPD instance.

token class-attribute instance-attribute

token: SecretStr | None = Field(
    alias="token", default_factory=secret_from_env("WATSONX_TOKEN", default=None)
)

Token to the CPD instance.

password class-attribute instance-attribute

password: SecretStr | None = Field(
    alias="password", default_factory=secret_from_env("WATSONX_PASSWORD", default=None)
)

Password to the CPD instance.

username class-attribute instance-attribute

username: SecretStr | None = Field(
    alias="username", default_factory=secret_from_env("WATSONX_USERNAME", default=None)
)

Username to the CPD instance.

instance_id class-attribute instance-attribute

instance_id: SecretStr | None = Field(
    alias="instance_id",
    default_factory=secret_from_env("WATSONX_INSTANCE_ID", default=None),
)

Instance_id of the CPD instance.

version class-attribute instance-attribute

version: SecretStr | None = None

Version of the CPD instance.

params class-attribute instance-attribute

params: dict | RerankParameters | None = None

Model parameters to use during request generation.

verify class-attribute instance-attribute

verify: str | bool | None = None

You can pass one of following as verify: * the path to a CA_BUNDLE file * the path of directory with certificates of trusted CAs * True - default path to truststore will be taken * False - no verification will be made

validate_model class-attribute instance-attribute

validate_model: bool = True

Model ID validation.

streaming class-attribute instance-attribute

streaming: bool = False

Whether to stream the results or not.

lc_secrets property

lc_secrets: dict[str, str]

Mapping of secret environment variables.

validate_environment

validate_environment() -> Self

Validate that credentials and python package exists in environment.

rerank

rerank(
    documents: Sequence[str | Document | dict], query: str, **kwargs: Any
) -> list[dict[str, Any]]

Rerank documents.

compress_documents

compress_documents(
    documents: Sequence[Document],
    query: str,
    callbacks: Callbacks | None = None,
    **kwargs: Any,
) -> Sequence[Document]

Compress documents using watsonx's rerank API.

PARAMETER	DESCRIPTION
documents	A sequence of documents to compress TYPE: Sequence[Document]
query	The query to use for compressing the documents TYPE: str
callbacks	Callbacks to run during the compression process TYPE: Callbacks | None DEFAULT: None
kwargs	Additional keyword args TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
Sequence[Document]	A sequence of compressed documents

acompress_documents async

acompress_documents(
    documents: Sequence[Document], query: str, callbacks: Callbacks | None = None
) -> Sequence[Document]

Async compress retrieved documents given the query context.

PARAMETER	DESCRIPTION
documents	The retrieved Document objects. TYPE: Sequence[Document]
query	The query context. TYPE: str
callbacks	Optional Callbacks to run during compression. TYPE: Callbacks | None DEFAULT: None

RETURNS	DESCRIPTION
Sequence[Document]	The compressed documents.