{"id":2934,"library":"docling-ibm-models","title":"Docling IBM Models","description":"This package provides AI models from IBM, including Large Language Models (LLMs) and embeddings, specifically designed for use with the LangChain framework. It is also an optional dependency for the Docling PDF conversion package, enabling advanced AI capabilities within Docling. Currently at version 3.13.0, it follows a relatively frequent release cadence, with updates typically occurring on a monthly basis.","status":"active","version":"3.13.0","language":"en","source_language":"en","source_url":"https://github.com/docling/docling-ibm-models","tags":["AI","PDF","IBM","NLP","LLM","Embeddings","LangChain","Watsonx"],"install":[{"cmd":"pip install docling-ibm-models","lang":"bash","label":"Install core package"},{"cmd":"pip install \"docling-ibm-models[docling]\"","lang":"bash","label":"Install with Docling support"}],"dependencies":[{"reason":"Core dependency for LLM and embeddings integration.","package":"langchain","optional":false},{"reason":"Core dependency for LangChain abstractions.","package":"langchain-core","optional":false},{"reason":"Core dependency for LangChain community integrations.","package":"langchain-community","optional":false},{"reason":"Dependency for text processing within LangChain.","package":"langchain-text-splitters","optional":false},{"reason":"IBM SDK for interacting with Watson Machine Learning services.","package":"ibm-watson-machine-learning","optional":false},{"reason":"IBM SDK for interacting with Generative AI services.","package":"ibm-generative-ai","optional":false},{"reason":"Foundation SDK for IBM Cloud services.","package":"ibm-cloud-sdk-core","optional":false},{"reason":"Used for certain embedding models.","package":"sentence-transformers","optional":false},{"reason":"Data validation and settings management.","package":"pydantic","optional":false},{"reason":"Optional dependency for integration with the Docling PDF conversion package.","package":"docling","optional":true}],"imports":[{"note":"Primary class for interacting with IBM Watsonx LLMs.","symbol":"WatsonxLLM","correct":"from docling_ibm_models.llms import WatsonxLLM"},{"note":"Primary class for interacting with IBM Watsonx embedding models.","symbol":"WatsonxEmbeddings","correct":"from docling_ibm_models.embeddings import WatsonxEmbeddings"}],"quickstart":{"code":"import os\nfrom docling_ibm_models.llms import WatsonxLLM\nfrom docling_ibm_models.embeddings import WatsonxEmbeddings\nfrom langchain.prompts import PromptTemplate\nfrom langchain_core.output_parsers import StrOutputParser\n\n# --- IBM Cloud Credentials (set as environment variables) ---\n# IBM_CLOUD_API_KEY=\"YOUR_IBM_CLOUD_API_KEY\"\n# IBM_CLOUD_REGION=\"us-south\" # Example: 'us-south', 'jp-tok', 'eu-de'\n# IBM_CLOUD_PROJECT_ID=\"YOUR_IBM_CLOUD_PROJECT_ID\"\n\napi_key = os.environ.get(\"IBM_CLOUD_API_KEY\", \"\")\nregion = os.environ.get(\"IBM_CLOUD_REGION\", \"us-south\")\nproject_id = os.environ.get(\"IBM_CLOUD_PROJECT_ID\", \"\")\n\nif not all([api_key, region, project_id]):\n    print(\"Please set IBM_CLOUD_API_KEY, IBM_CLOUD_REGION, and IBM_CLOUD_PROJECT_ID environment variables.\")\n    print(\"Skipping LLM and Embeddings quickstart examples.\")\nelse:\n    try:\n        print(\"\\n--- Initializing WatsonxLLM ---\")\n        # Initialize the WatsonxLLM\n        llm = WatsonxLLM(\n            api_key=api_key,\n            region=region,\n            project_id=project_id,\n            model_id=\"google/flan-ul2\", # Example model, check available models for your region\n            temperature=0.7,\n            max_new_tokens=200\n        )\n\n        # Create a simple LangChain chain\n        prompt = PromptTemplate.from_template(\"What is the capital of {country}?\")\n        output_parser = StrOutputParser()\n        chain = prompt | llm | output_parser\n\n        # Invoke the chain\n        response = chain.invoke({\"country\": \"France\"})\n        print(f\"Capital of France: {response.strip()}\")\n\n        print(\"\\n--- Initializing WatsonxEmbeddings ---\")\n        # Initialize WatsonxEmbeddings\n        embeddings_model = WatsonxEmbeddings(\n            api_key=api_key,\n            region=region,\n            project_id=project_id,\n            model_id=\"intfloat/multilingual-e5-large\" # Example embedding model\n        )\n\n        # Embed documents\n        texts_to_embed = [\"Hello world from IBM models\", \"Docling integration example\"]\n        text_embeddings = embeddings_model.embed_documents(texts_to_embed)\n        print(f\"Embeddings for '{texts_to_embed[0]}' (first 5 dims): {text_embeddings[0][:5]}...\")\n\n    except Exception as e:\n        print(f\"\\nAn error occurred during quickstart execution: {e}\")\n        print(\"Ensure your IBM Cloud credentials are correct, model IDs are valid for your project/region, and you have necessary entitlements.\")","lang":"python","description":"This quickstart demonstrates how to initialize and use `WatsonxLLM` and `WatsonxEmbeddings` provided by `docling-ibm-models` within the LangChain framework. It requires IBM Cloud API Key, region, and project ID, typically provided via environment variables. The example shows generating text with an LLM and creating embeddings for text."},"warnings":[{"fix":"Set `IBM_CLOUD_API_KEY`, `IBM_CLOUD_REGION`, and `IBM_CLOUD_PROJECT_ID` environment variables, or pass them directly to the `WatsonxLLM` or `WatsonxEmbeddings` constructor. Ensure the API key has necessary permissions for the chosen service and models.","message":"IBM Cloud API Key, region, and project ID are mandatory for all model interactions with Watsonx.ai services and must be correctly configured. Failure to provide these credentials or providing incorrect ones will result in authentication or authorization errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the IBM Watsonx.ai documentation for available models in your target region and ensure your IBM Cloud project has the necessary access permissions. Test with a common, publicly available model first, or verify your model IDs and access through the IBM Cloud console.","message":"The availability and compatibility of specific LLM or embedding models (e.g., 'google/flan-ul2', 'intfloat/multilingual-e5-large') can vary by IBM Cloud region and your project's entitlements. Using an unavailable or unauthorized model will result in runtime errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If integrating with `docling`, ensure you install `docling` compatible with the version specified in `docling-ibm-models`'s `pyproject.toml`'s optional dependencies. The safest approach is to install `docling-ibm-models` with its `docling` extra: `pip install \"docling-ibm-models[docling]\"`.","message":"When using `docling-ibm-models` with the main `docling` package, be aware that `docling-ibm-models` may pin `docling` to a specific, older version (e.g., `docling==0.1.0`) in its optional dependencies. Installing a newer `docling` version independently can lead to compatibility issues or unexpected behavior.","severity":"breaking","affected_versions":"Versions >= 3.x where `docling` is specified as an optional, pinned dependency."},{"fix":"Ensure adequate disk space and network connectivity for the environment where the models are initialized. Pre-downloading models or configuring cache directories might be necessary for production deployments.","message":"Depending on the specific models or underlying libraries (e.g., `sentence-transformers` for some embeddings), initial usage might trigger large model downloads, consuming significant disk space and bandwidth. This can impact application startup time and resource usage, especially in containerized environments.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}