# https://github.com/langchain-ai/langchain 项目说明书
生成时间：2026-05-15 21:57:00 UTC
## 目录
- [Introduction to LangChain](#introduction)
- [Getting Started with LangChain](#getting-started)
- [Runnable and Execution Model](#runnable-execution)
- [Messages and Prompt System](#messages-system)
- [Callbacks and Tracing Infrastructure](#callbacks-tracing)
- [Chat Models and Embeddings](#chat-models-embeddings)
- [Agents Framework](#agents-framework)
- [Tools and Toolkits](#tools-integrations)
- [Document Loaders and Text Processing](#document-loaders)
- [Vector Stores and Retrievers](#vectorstores-retrievers)
## Introduction to LangChain
### 相关页面
相关主题：[Runnable and Execution Model](#runnable-execution), [Getting Started with LangChain](#getting-started)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
- [libs/partners/openai/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/openai/README.md)
- [libs/partners/anthropic/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/anthropic/README.md)
- [libs/partners/huggingface/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/huggingface/README.md)
- [libs/langchain/langchain_classic/chains/api/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/chains/api/base.py)
- [libs/partners/ollama/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/ollama/README.md)
- [libs/partners/chroma/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/chroma/README.md)
# Introduction to LangChain
## Overview
LangChain is a comprehensive framework designed for building agents and LLM-powered applications. It enables developers to chain together interoperable components and third-party integrations to simplify AI application development, while maintaining flexibility as underlying technologies evolve.
LangChain follows a modular architecture where core functionality is separated into specialized packages. The main `langchain` package serves as the primary interface for most use cases, with partner packages providing dedicated integrations for specific providers.
## Architecture Overview
LangChain's architecture consists of several key layers working together to provide a seamless development experience:
```mermaid
graph TD
A[Application Layer] --> B[langchain Package]
B --> C[langchain-classic]
B --> D[langchain-core]
C --> E[Chains & Components]
C --> F[Community Re-exports]
D --> G[Core Abstractions]
H[Partner Packages] --> B
H --> I[OpenAI, Anthropic, HuggingFace, etc.]
```
## Core Packages
### langchain-core
The foundational package containing core abstractions and interfaces that all other LangChain packages depend on. This includes base classes for language models, prompts, callbacks, and other fundamental components.
### langchain-classic
The classic LangChain package containing chains, `langchain-community` re-exports, indexing API, and deprecated functionality. In most cases, developers should use the main `langchain` package instead.
## Partner Integrations
LangChain provides dedicated partner packages for various LLM providers and services. Each package is independently maintained and optimized for its specific provider.
### LLM Provider Packages
| Package | Provider | Purpose | Install Command |
|---------|----------|---------|-----------------|
| `langchain-openai` | OpenAI | OpenAI SDK integration | `pip install langchain-openai` |
| `langchain-anthropic` | Anthropic | Claude models integration | `pip install langchain-anthropic` |
| `langchain-huggingface` | Hugging Face | Transformers & embeddings | `pip install langchain-huggingface` |
| `langchain-ollama` | Ollama | Local model inference | `pip install langchain-ollama` |
| `langchain-deepseek` | DeepSeek | DeepSeek API integration | `pip install langchain-deepseek` |
| `langchain-groq` | Groq | Groq API integration | `pip install langchain-groq` |
| `langchain-fireworks` | Fireworks.ai | Fireworks API integration | `pip install langchain-fireworks` |
| `langchain-perplexity` | Perplexity | Perplexity API integration | `pip install langchain-perplexity` |
| `langchain-xai` | xAI | xAI API integration | `pip install langchain-xai` |
| `langchain-openrouter` | OpenRouter | Unified multi-provider API | `pip install langchain-openrouter` |
### Vector Store & Search Packages
| Package | Provider | Purpose | Install Command |
|---------|----------|---------|-----------------|
| `langchain-chroma` | Chroma | Vector database integration | `pip install langchain-chroma` |
| `langchain-exa` | Exa | Web search API for AI | `pip install langchain-exa` |
| `langchain-nomic` | Nomic | Embedding & visualization | `pip install langchain-nomic` |
## Quick Start
The simplest way to get started with LangChain is using the `init_chat_model` function for initializing chat models:
```python
from langchain.chat_models import init_chat_model
model = init_chat_model("openai:gpt-5.4")
result = model.invoke("Hello, world!")
```
For more advanced customization or agent orchestration, LangChain recommends using [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview), their framework for building controllable agent workflows.
## Installation Options
LangChain offers flexible installation options to suit different needs:
```bash
# Base installation
pip install langchain
# With specific integrations
pip install langchain-huggingface[full]
```
The `[full]` extra for packages like `langchain-huggingface` includes additional dependencies such as `sentence-transformers>=5.2.0` and `transformers>=5.0.0` for local inference capabilities.
## Key Features
### Interoperability
LangChain emphasizes interoperability through standardized interfaces. Components can be easily swapped and combined, allowing developers to:
- Switch between different LLM providers without code changes
- Combine multiple integrations in a single application
- Future-proof applications against technology changes
### Flexible Abstraction Layers
LangChain provides multiple levels of abstraction:
- **High-level chains**: Quick starts for common patterns
- **Low-level components**: Fine-grained control for advanced use cases
The framework grows with your application's complexity, allowing you to start simple and add sophistication as needed.
### Security Considerations
When building applications with LangChain, security should be a primary concern. The framework includes built-in protections for components like API chains:
> **Security Note**: The API chain uses the requests toolkit to make `GET`, `POST`, `PATCH`, `PUT`, and `DELETE` requests to an API. Exercise care in who is allowed to use this chain. Control access to who can submit requests and what network access it has.
## Additional Resources
LangChain provides comprehensive documentation and support:
| Resource | URL |
|----------|-----|
| Full Documentation | [docs.langchain.com](https://docs.langchain.com/oss/python/langchain/overview) |
| API Reference | [reference.langchain.com/python](https://reference.langchain.com/python) |
| Community Forum | [forum.langchain.com](https://forum.langchain.com) |
| Chat with Docs | [chat.langchain.com](https://chat.langchain.com/) |
| LangChain Academy | [academy.langchain.com](https://academy.langchain.com/) |
| Contributing Guide | [docs.langchain.com/contributing](https://docs.langchain.com/oss/python/contributing/overview) |
## Related Projects
For specialized use cases, LangChain offers additional projects:
- **LangGraph**: Framework for building controllable agent workflows
- **Deep Agents**: Higher-level package with built-in capabilities for planning, subagents, and file system usage
- **LangSmith**: Platform for developing, debugging, and deploying AI agents
- **LangChain.js**: JavaScript/TypeScript equivalent library
## Ecosystem Diagram
```mermaid
graph LR
A[Developers] --> B[langchain Package]
B --> C[Core Abstractions]
B --> D[Partner Integrations]
D --> E[LLM Providers]
D --> F[Vector Stores]
D --> G[Search APIs]
B --> H[LangGraph]
B --> I[LangSmith]
C --> J[Chat Models]
C --> K[Embeddings]
C --> L[Tools]
C --> M[Memory]
```
LangChain continues to evolve with an active open-source community. Contributions are welcome in the form of new features, improved infrastructure, or better documentation.
---
## Getting Started with LangChain
### 相关页面
相关主题：[Introduction to LangChain](#introduction), [Runnable and Execution Model](#runnable-execution)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
- [libs/partners/openai/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/openai/README.md)
- [libs/partners/anthropic/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/anthropic/README.md)
- [libs/partners/huggingface/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/huggingface/README.md)
- [libs/partners/ollama/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/ollama/README.md)
- [libs/partners/deepseek/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/deepseek/README.md)
- [libs/partners/groq/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/groq/README.md)
# Getting Started with LangChain
LangChain is a framework for building agents and LLM-powered applications. It enables developers to chain together interoperable components and third-party integrations to simplify AI application development while future-proofing decisions as the underlying technology evolves. 资料来源：[README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
## Installation
### Base Installation
The core LangChain package can be installed via pip or uv:
```bash
pip install langchain
# or
uv add langchain
```
资料来源：[README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
### Integration Packages
LangChain uses a modular architecture with partner-specific packages. Each integration is distributed as a separate package:
| Package | Purpose | Install Command |
|---------|---------|-----------------|
| `langchain-openai` | OpenAI models (GPT-4, GPT-5, etc.) | `pip install langchain-openai` |
| `langchain-anthropic` | Anthropic models (Claude) | `pip install langchain-anthropic` |
| `langchain-huggingface` | Hugging Face models | `pip install langchain-huggingface` |
| `langchain-ollama` | Ollama local models | `pip install langchain-ollama` |
| `langchain-deepseek` | DeepSeek models | `pip install langchain-deepseek` |
| `langchain-groq` | Groq models | `pip install langchain-groq` |
资料来源：[libs/partners/openai/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/openai/README.md), [libs/partners/anthropic/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/anthropic/README.md), [libs/partners/ollama/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/ollama/README.md), [libs/partners/deepseek/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/deepseek/README.md), [libs/partners/groq/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/groq/README.md)
### Full Installation with Dependencies
For packages requiring additional dependencies like `sentence-transformers` or `transformers`:
```bash
pip install langchain-huggingface[full]
```
> **Note:** The `[full]` extra includes `sentence-transformers>=5.2.0` and `transformers>=5.0.0`. 资料来源：[libs/partners/huggingface/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/huggingface/README.md)
## Quick Start
### Initializing a Chat Model
LangChain provides a unified interface for initializing chat models using `init_chat_model`:
```python
from langchain.chat_models import init_chat_model
model = init_chat_model("openai:gpt-5.4")
result = model.invoke("Hello, world!")
```
The `init_chat_model` function supports model providers through a prefixed model string format (e.g., `openai:gpt-5.4`, `anthropic:claude-3-opus`). 资料来源：[README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
### Supported Providers
LangChain integrates with multiple model providers:
- **OpenAI** - GPT-4, GPT-5, and other OpenAI models through the `openai` SDK 资料来源：[libs/partners/openai/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/openai/README.md)
- **Anthropic** - Claude models through Anthropic's API 资料来源：[libs/partners/anthropic/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/anthropic/README.md)
- **Hugging Face** - Both API-based and local inference via transformers 资料来源：[libs/partners/huggingface/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/huggingface/README.md)
- **Ollama** - Local model inference 资料来源：[libs/partners/ollama/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/ollama/README.md)
- **DeepSeek** - DeepSeek models 资料来源：[libs/partners/deepseek/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/deepseek/README.md)
- **Groq** - Groq inference 资料来源：[libs/partners/groq/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/groq/README.md)
## Architecture Overview
LangChain provides flexible abstraction layers allowing developers to work at the level of abstraction that suits their needs:
```mermaid
graph TD
A[LangChain Application] --> B[High-Level Chains]
A --> C[Low-Level Components]
B --> D[Agents]
B --> E[Chains]
C --> F[LLMs]
C --> G[Prompts]
C --> H[Tools]
F --> I[Provider Integrations]
I --> J[OpenAI]
I --> K[Anthropic]
I --> L[HuggingFace]
I --> M[Ollama]
```
- **High-level chains** - Quick starts for common patterns
- **Low-level components** - Fine-grained control for custom implementations
资料来源：[README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
## Ecosystem
LangChain consists of multiple interconnected packages:
```mermaid
graph LR
A[Core LangChain] --> B[langchain-core]
A --> C[Partner Packages]
A --> D[langchain-community]
B --> E[Base abstractions]
C --> F[Provider-specific]
D --> G[Community integrations]
```
### Package Structure
| Package | Description |
|---------|-------------|
| `langchain-core` | Core abstractions and interfaces |
| `langchain` | Main framework (chains, agents, core functionality) |
| `langchain-community` | Community-contributed integrations |
| Partner packages | Provider-specific integrations (openai, anthropic, etc.) |
## Documentation Resources
For comprehensive learning and reference:
| Resource | URL | Purpose |
|----------|-----|---------|
| Main Docs | [docs.langchain.com](https://docs.langchain.com/oss/python/langchain/overview) | Conceptual guides, overviews, tutorials |
| API Reference | [reference.langchain.com/python](https://reference.langchain.com/python) | Complete API documentation |
| Chat LangChain | [chat.langchain.com](https://chat.langchain.com/) | Interactive documentation chat |
| LangChain Forum | [forum.langchain.com](https://forum.langchain.com) | Community discussions |
| LangChain Academy | [academy.langchain.com](https://academy.langchain.com/) | Free courses on LangChain |
资料来源：[README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
## Advanced Usage
### Building Agents
For advanced customization and agent orchestration, LangChain recommends using [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview), a framework for building controllable agent workflows. 资料来源：[README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
### Development and Debugging
For developing, debugging, and deploying AI agents and LLM applications, [LangSmith](https://docs.langchain.com/langsmith/home) provides comprehensive tooling. 资料来源：[README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
## Contributing
LangChain is an open-source project welcoming contributions in the form of new features, improved infrastructure, or better documentation. See the [Contributing Guide](https://docs.langchain.com/oss/python/contributing/overview) for details on how to get involved. 资料来源：[README.md](https://github.com/langchain-ai/langchain/blob/main/README.md), [libs/partners/openai/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/openai/README.md)
---
## Runnable and Execution Model
### 相关页面
相关主题：[Introduction to LangChain](#introduction), [Callbacks and Tracing Infrastructure](#callbacks-tracing), [Agents Framework](#agents-framework)
相关源码文件
以下源码文件用于生成本页说明：
- [libs/core/langchain_core/runnables/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/base.py)
- [libs/core/langchain_core/runnables/config.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/config.py)
- [libs/core/langchain_core/runnables/retry.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/retry.py)
- [libs/core/langchain_core/runnables/branch.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/branch.py)
- [libs/core/langchain_core/runnables/graph.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/graph.py)
# Runnable and Execution Model
## Overview
The **Runnable** interface is the foundational abstraction in LangChain for creating composable, executable units of work. Every component in LangChain—including chains, models, tools, and utilities—implements the Runnable protocol, enabling uniform composition, execution, and error handling across the entire framework.
The execution model provides both synchronous and asynchronous invocation patterns, retry mechanisms, configurable runtime parameters, and conditional branching capabilities. This design allows developers to build complex AI applications by composing simple, reusable components into sophisticated pipelines.
资料来源：[libs/core/langchain_core/runnables/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/base.py)
---
## Core Interface
### Base Runnable Protocol
The `Runnable` base class defines the standard interface that all LangChain components implement. Every Runnable must support the following invocation patterns:
| Method | Description | Input | Output |
|--------|-------------|-------|--------|
| `invoke` | Synchronous single input processing | `Input` | `Output` |
| `ainvoke` | Asynchronous single input processing | `Input` | `Awaitable[Output]` |
| `batch` | Synchronous batch processing | `List[Input]` | `List[Output]` |
| `abatch` | Asynchronous batch processing | `List[Input]` | `Awaitable[List[Output]]` |
| `stream` | Synchronous streaming output | `Input` | `Iterator[Output]` |
| `astream` | Asynchronous streaming output | `Input` | `AsyncIterator[Output]` |
资料来源：[libs/core/langchain_core/runnables/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/base.py)
### Runnable Composition
Runnables can be composed using the pipe operator (`|`), creating a `RunnableSequence`. This allows chaining multiple components where the output of one becomes the input of the next.
```mermaid
graph LR
A[Input] --> B[Runnable 1]
B --> C[Runnable 2]
C --> D[Runnable 3]
D --> E[Output]
```
Example composition pattern:
```python
from langchain_core.runnables import RunnableLambda
chain = (
RunnableLambda(lambda x: x.upper())
| RunnableLambda(lambda x: f"Result: {x}")
)
result = chain.invoke("hello") # "Result: HELLO"
```
资料来源：[libs/core/langchain_core/runnables/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/base.py)
---
## Execution Configuration
### RunnableConfig
The `RunnableConfig` class encapsulates runtime configuration that controls how a Runnable executes. Configuration is passed through the invocation chain and can influence retry behavior, callback invocation, metadata tagging, and execution constraints.
| Parameter | Type | Description |
|-----------|------|-------------|
| `tags` | `List[str]` | Tags for tracing and organization |
| `metadata` | `Dict[str, Any]` | Metadata attached to the run |
| `callbacks` | `Callbacks` | Callback handlers for monitoring |
| `max_concurrency` | `int | None` | Maximum concurrent executions |
| `recursion_limit` | `int` | Maximum recursion depth (default: 25) |
| `run_name` | `str | None` | Name identifier for this run |
资料来源：[libs/core/langchain_core/runnables/config.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/config.py)
### Configuration Propagation
Configuration flows through the Runnable sequence automatically. When invoking a chain:
```python
from langchain_core.runnables import RunnableConfig
config = RunnableConfig(
tags=["production", "v1"],
metadata={"user_id": "123"},
run_name="chat_completion"
)
# Config is automatically passed through the chain
result = chain.invoke(input, config=config)
```
资料来源：[libs/core/langchain_core/runnables/config.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/config.py)
---
## Retry Mechanism
### Retry Configuration
The retry system provides fault tolerance through the `RetryConfig` class, which defines retry policies for transient failures.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `max_attempts` | `int` | 3 | Maximum retry attempts |
| `initial_interval` | `float` | 1.0 | Initial delay between retries (seconds) |
| `growth_factor` | `float` | 2.0 | Exponential backoff multiplier |
| `max_interval` | `float` | 10.0 | Maximum delay cap (seconds) |
| `retry_on` | `Tuple[Type[Exception], ...]` | `(Exception,)` | Exception types to retry |
资料来源：[libs/core/langchain_core/runnables/retry.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/retry.py)
### Retry Execution Flow
```mermaid
graph TD
A[Invoke Runnable] --> B{Success?}
B -->|Yes| C[Return Result]
B -->|No| D{Attempts < Max?}
D -->|Yes| E[Wait with Backoff]
E --> F[Retry Invocation]
F --> B
D -->|No| G[Raise Exception]
```
### Applying Retry to Runnables
```python
from langchain_core.runnables.retry import RetryConfig
# Configure retry policy
retry_config = RetryConfig(
max_attempts=3,
initial_interval=0.5,
growth_factor=2.0,
retry_on=(ConnectionError, TimeoutError)
)
# Apply to any Runnable
retry_chain = chain.with_retry(retry_config)
```
资料来源：[libs/core/langchain_core/runnables/retry.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/retry.py)
---
## Branching Logic
### RunnableBranch
The `RunnableBranch` class provides conditional execution paths within a chain. It evaluates a series of conditions and executes the corresponding Runnable when a condition is met.
| Parameter | Type | Description |
|-----------|------|-------------|
| `branches` | `List[Tuple[Runnable, Runnable]]` | Pairs of condition and branch runnable |
| `default` | `Runnable | None` | Default branch when no conditions match |
资料来源：[libs/core/langchain_core/runnables/branch.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/branch.py)
### Branch Execution Flow
```mermaid
graph TD
A[Input] --> B[Condition 1?]
B -->|True| C[Branch 1]
B -->|False| D[Condition 2?]
D -->|True| E[Branch 2]
D -->|False| F[Default Branch]
C --> G[Output]
E --> G
F --> G
```
### Branching Example
```python
from langchain_core.runnables.branch import RunnableBranch
branch = RunnableBranch(
(lambda x: x.get("type") == "greeting", greeting_chain),
(lambda x: x.get("type") == "question", question_chain),
default_chain # Executes when no conditions match
)
result = branch.invoke({"type": "greeting", "content": "Hello!"})
```
资料来源：[libs/core/langchain_core/runnables/branch.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/branch.py)
---
## Graph Model
### RunnableGraph
The `RunnableGraph` class provides a visual and programmatic representation of a Runnable sequence as a directed graph. This enables inspection, serialization, and visualization of complex chain architectures.
| Method | Description |
|--------|-------------|
| `add_node(name, runnable)` | Add a node to the graph |
| `add_edge(source, target)` | Add a directed edge between nodes |
| `set_entry_point(name)` | Define the starting node |
| `get_graph()` | Retrieve the graph representation |
资料来源：[libs/core/langchain_core/runnables/graph.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/graph.py)
### Graph Visualization
```mermaid
graph TD
A[entry_point] --> B[process_input]
B --> C{Validation?}
C -->|Pass| D[execute_step_1]
C -->|Fail| E[error_handler]
D --> F[execute_step_2]
F --> G[finalize]
E --> G
```
### Graph Construction
```python
from langchain_core.runnables.graph import RunnableGraph
graph = RunnableGraph()
graph.add_node("input", input_processor)
graph.add_node("process", processing_chain)
graph.add_node("output", output_formatter)
graph.set_entry_point("input")
graph.add_edge("input", "process")
graph.add_edge("process", "output")
# Visualize or inspect the graph
visualization = graph.get_graph()
```
资料来源：[libs/core/langchain_core/runnables/graph.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/graph.py)
---
## Type Hints and Generics
The Runnable interface uses Python generics to ensure type safety across the chain:
```python
class Runnable[Input, Output](BaseRunnable):
"""Base class for generic Runnable with typed inputs and outputs."""
def invoke(self, input: Input, config: RunnableConfig | None = None) -> Output:
...
```
Type preservation through the chain enables:
- Static type checking with mypy/pyright
- IDE autocomplete for intermediate outputs
- Runtime type validation
资料来源：[libs/core/langchain_core/runnables/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/runnables/base.py)
---
## Summary
The Runnable and Execution Model forms the backbone of LangChain's architecture:
| Component | Purpose |
|-----------|---------|
| **Runnable Protocol** | Unified interface for all executable components |
| **Execution Methods** | Sync/async, single/batch, and streaming invocations |
| **Configuration** | Runtime parameters propagated through chains |
| **Retry Logic** | Automatic retry with exponential backoff |
| **Branching** | Conditional execution paths |
| **Graph Model** | Visualization and inspection of chain structure |
This design enables developers to build complex AI workflows by composing simple, reusable, and testable components with consistent behavior and error handling.
---
## Messages and Prompt System
### 相关页面
相关主题：[Chat Models and Embeddings](#chat-models-embeddings)
I cannot generate an accurate technical wiki page about the "Messages and Prompt System" because the context provided does not contain the actual source code files listed in the `` block. The context only includes README documentation files from various partner packages (huggingface, anthropic, openai, etc.) and some API chain code examples.
The required source files for generating this wiki are:
- `libs/core/langchain_core/messages/__init__.py`
- `libs/core/langchain_core/messages/chat.py`
- `libs/core/langchain_core/messages/content.py`
- `libs/core/langchain_core/messages/block_translators/__init__.py`
- `libs/core/langchain_core/prompts/__init__.py`
- `libs/core/langchain_core/prompts/chat.py`
**What the context contains instead:**
- Partner package READMEs (huggingface, anthropic, ollama, chroma, openrouter, groq, exa, deepseek, perplexity, xai, nomic, openai)
- `libs/langchain/langchain_classic/chains/api/base.py` (API chain implementation)
- `libs/standard-tests/README.md` (testing utilities documentation)
To generate a comprehensive and accurate wiki page about the Messages and Prompt System, I need access to the actual implementation source files. Please provide the content of the files listed in the `` block so I can analyze them and create the technical documentation accordingly.
---
## Callbacks and Tracing Infrastructure
### 相关页面
相关主题：[Runnable and Execution Model](#runnable-execution)
相关源码文件
以下源码文件用于生成本页说明：
- [libs/core/langchain_core/callbacks/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/callbacks/__init__.py)
- [libs/core/langchain_core/callbacks/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/callbacks/base.py)
- [libs/core/langchain_core/callbacks/manager.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/callbacks/manager.py)
- [libs/core/langchain_core/tracers/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tracers/__init__.py)
- [libs/core/langchain_core/tracers/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tracers/base.py)
- [libs/core/langchain_core/tracers/event_stream.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tracers/event_stream.py)
# Callbacks and Tracing Infrastructure
## Overview
The LangChain callbacks and tracing infrastructure provides a unified system for observability, monitoring, and event propagation across LangChain components. This system enables developers to track LLM invocations, chain executions, tool usage, and custom events throughout the application lifecycle.
LangChain follows a monorepo structure where core primitives and abstractions are located in `libs/core/langchain_core/`, with callback and tracer implementations residing in dedicated modules under `langchain_core.callbacks` and `langchain_core.tracers` respectively. 资料来源：[libs/README.md](libs/README.md)
## Architecture Overview
```mermaid
graph TD
A[Application Code] --> B[CallbackManager]
B --> C[BaseCallbackHandler]
C --> D[Tracer Implementations]
C --> E[Custom Handlers]
D --> F[LangSmith]
D --> G[Other Exporters]
B --> H[AsyncCallbackManager]
H --> C
style A fill:#e1f5fe
style F fill:#c8e6c9
style G fill:#c8e6c9
```
## Callback System
### Core Components
The callback system in LangChain is built around the following key abstractions:
| Component | File Location | Purpose |
|-----------|--------------|---------|
| `BaseCallbackHandler` | `libs/core/langchain_core/callbacks/base.py` | Abstract base class for all callback handlers |
| `CallbackManager` | `libs/core/langchain_core/callbacks/manager.py` | Manages synchronous callback execution |
| `AsyncCallbackManager` | `libs/core/langchain_core/callbacks/manager.py` | Manages asynchronous callback execution |
| `Callbacks` | `libs/core/langchain_core/callbacks/__init__.py` | Public API exports |
### BaseCallbackHandler
The `BaseCallbackHandler` class defines the contract for all callback implementations. It provides methods for intercepting various events during chain execution:
```python
# Conceptual structure
class BaseCallbackHandler:
"""Base class for callback handlers."""
def on_llm_start(self, ...):
"""Called when LLM starts processing."""
pass
def on_llm_end(self, ...):
"""Called when LLM finishes processing."""
pass
def on_chain_start(self, ...):
"""Called when a chain starts execution."""
pass
def on_chain_end(self, ...):
"""Called when a chain finishes execution."""
pass
def on_tool_start(self, ...):
"""Called when a tool starts execution."""
pass
def on_tool_end(self, ...):
"""Called when a tool finishes execution."""
pass
```
资料来源：[libs/core/langchain_core/callbacks/base.py](libs/core/langchain_core/callbacks/base.py)
### CallbackManager
The `CallbackManager` coordinates multiple callback handlers and ensures proper event propagation:
```mermaid
sequenceDiagram
participant App as Application
participant CM as CallbackManager
participant H1 as Handler 1
participant H2 as Handler 2
participant LC as LangChain Component
App->>CM: add_handler(handler)
App->>LC: invoke(inputs, callbacks=CM)
LC->>CM: on_chain_start(...)
CM->>H1: on_chain_start(...)
CM->>H2: on_chain_start(...)
LC->>CM: on_llm_start(...)
CM->>H1: on_llm_start(...)
CM->>H2: on_llm_start(...)
LC->>CM: on_llm_end(...)
CM->>H1: on_llm_end(...)
CM->>H2: on_llm_end(...)
LC->>CM: on_chain_end(...)
CM->>H1: on_chain_end(...)
CM->>H2: on_chain_end(...)
```
Key features of `CallbackManager`:
- Manages a list of registered handlers
- Supports handler persistence via `copy()` method
- Provides context management for nested callbacks
- Handles both sync and async handlers transparently
资料来源：[libs/core/langchain_core/callbacks/manager.py](libs/core/langchain_core/callbacks/manager.py)
### Callback Configuration Options
| Parameter | Type | Description |
|-----------|------|-------------|
| `tags` | `list[str]` | Tags for filtering callbacks |
| ` inheritable` | `bool` | Whether callbacks propagate to child runs |
| `metadata` | `dict` | Additional context metadata |
## Tracing Infrastructure
### Overview
The tracing subsystem extends the callback system to provide persistent, exportable traces of LangChain executions. Tracers are specialized callback handlers that serialize execution data for external systems like LangSmith.
```mermaid
graph LR
A[LangChain Execution] --> B[Tracer Base]
B --> C[Core Tracer]
B --> D[Event Stream Tracer]
C --> E[LangChain Tracers]
D --> F[Async Event Streaming]
E --> G[LangSmith]
E --> H[Other Exporters]
```
资料来源：[libs/core/langchain_core/tracers/__init__.py](libs/core/langchain_core/tracers/__init__.py)
### Tracer Base Class
Located in `libs/core/langchain_core/tracers/base.py`, the base tracer provides:
| Feature | Description |
|---------|-------------|
| Run tracking | Maintains state for all active and completed runs |
| Event serialization | Converts callback events to exportable format |
| Parent-child relationships | Manages nested execution traces |
| Persistence layer | Abstract interface for storing traces |
### Event Stream Tracer
The `EventStreamTracer` provides an async-native interface for streaming trace events:
```python
# Conceptual implementation
class EventStreamTracer:
"""Tracer that supports async event streaming."""
async def astream_events(self, ...):
"""Async generator for trace events."""
while True:
event = await self._get_next_event()
if event is None:
break
yield event
```
This tracer enables real-time event streaming capabilities for applications requiring live observability.
资料来源：[libs/core/langchain_core/tracers/event_stream.py](libs/core/langchain_core/tracers/event_stream.py)
## Integration Patterns
### Passing Callbacks to Components
Callbacks can be passed to LangChain components at initialization or invocation time:
```python
from langchain_core.callbacks import CallbackManager, BaseCallbackHandler
class MyHandler(BaseCallbackHandler):
def on_chain_start(self, serialized, inputs, **kwargs):
print(f"Chain starting with inputs: {inputs}")
handler = MyHandler()
callback_manager = CallbackManager(handlers=[handler])
# Pass to model
response = model.invoke("Hello", config={"callbacks": callback_manager})
# Pass to chain
chain.invoke(input, config={"callbacks": callback_manager})
```
### Using Tracers for Persistence
```python
from langchain_core.tracers import LangChainTracer
tracer = LangChainTracer(project_name="my-project")
chain.invoke(
input,
config={"callbacks": [tracer]}
)
```
## Data Flow
```mermaid
graph TD
subgraph Execution
A[User Code] --> B[Chain/Model]
B --> C[CallbackManager]
end
subgraph EventPropagation
C --> D[on_chain_start]
D --> E[on_llm_start]
E --> F[LLM Execution]
F --> G[on_llm_end]
G --> H[on_chain_end]
end
subgraph Observability
H --> I[Tracer]
I --> J[Run Tree]
J --> K[Export/Store]
K --> L[LangSmith/Other]
end
style L fill:#fff3e0
style K fill:#fff3e0
```
## Best Practices
1. **Handler Isolation**: Create separate callback handlers for different concerns (monitoring, tracing, debugging)
2. **Performance Consideration**: Avoid expensive operations in synchronous callback handlers; prefer async handlers for I/O-bound operations
3. **Memory Management**: Use `copy()` on `CallbackManager` when spawning child executions to prevent handler leakage
4. **Tag-Based Filtering**: Use tags to selectively enable/disable callbacks in different environments
5. **Tracer Configuration**: Configure tracers with appropriate project names and metadata for proper organization in observability platforms
## Related Documentation
- [LangChain Core API Reference](https://reference.langchain.com/python/langchain_core)
- [LangChain Documentation](https://docs.langchain.com/oss/python/langchain/overview)
- [LangSmith Integration](https://docs.langchain.com/langsmith/home)
## Package Structure
The callbacks and tracing infrastructure is maintained in the core library:
```
libs/core/langchain_core/
├── callbacks/
│ ├── __init__.py # Public exports
│ ├── base.py # BaseCallbackHandler
│ └── manager.py # CallbackManager, AsyncCallbackManager
└── tracers/
├── __init__.py # Public exports
├── base.py # Base tracer implementations
└── event_stream.py # Async event streaming support
```
资料来源：[libs/README.md](libs/README.md)
---
## Chat Models and Embeddings
### 相关页面
相关主题：[Introduction to LangChain](#introduction), [Messages and Prompt System](#messages-system)
相关源码文件
以下源码文件用于生成本页说明：
- [libs/core/langchain_core/language_models/chat_models.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/language_models/chat_models.py)
- [libs/core/langchain_core/language_models/llms.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/language_models/llms.py)
- [libs/core/langchain_core/embeddings/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/embeddings/__init__.py)
- [libs/core/langchain_core/embeddings/embeddings.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/embeddings/embeddings.py)
- [libs/core/langchain_core/language_models/model_profile.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/language_models/model_profile.py)
# Chat Models and Embeddings
## Overview
Chat Models and Embeddings are foundational components within the LangChain ecosystem that enable interaction with large language models (LLMs) for conversational and vector-based AI applications. These abstractions provide standardized interfaces for working with different model providers while maintaining flexibility for customization.
LangChain provides two primary categories of language model interfaces:
| Category | Purpose | Key Classes |
|----------|---------|-------------|
| **Chat Models** | Handle conversational interactions with message-based APIs | `BaseChatModel`, `BaseMessage` |
| **Embeddings** | Convert text into vector representations for similarity search | `Embeddings`, `BaseEmbeddings` |
| **LLMs** | Traditional text-in, text-out language model interfaces | `BaseLLM`, `LLM` |
资料来源：[libs/core/langchain_core/language_models/chat_models.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/language_models/chat_models.py)
## Architecture
### High-Level Component Hierarchy
```mermaid
graph TD
A[LangChain Core] --> B[Language Models]
A --> C[Embeddings]
B --> D[BaseChatModel]
B --> E[BaseLLM]
D --> F[Provider Implementations]
E --> G[Provider Implementations]
C --> H[Embeddings Interface]
H --> I[Embedding Providers]
F --> J[OpenAI Chat]
F --> K[Anthropic Chat]
F --> L[Ollama Chat]
I --> M[OpenAI Embeddings]
I --> N[HuggingFace Embeddings]
I --> O[Ollama Embeddings]
```
### Chat Model Initialization Pattern
The preferred method for initializing chat models in LangChain is through the `init_chat_model` function, which provides a unified initialization interface across providers.
```python
from langchain.chat_models import init_chat_model
# Initialize with provider prefix
model = init_chat_model("openai:gpt-4o-mini", temperature=0)
# Invoke the model
result = model.invoke("Hello, world!")
```
资料来源：[README.md](https://github.com/langchain-ai/langchain/blob/main/README.md)
## Chat Models
### BaseChatModel Interface
The `BaseChatModel` class serves as the foundation for all chat model implementations in LangChain. It extends `BaseLanguageModel` and provides standardized methods for generating responses from conversation histories.
#### Key Methods
| Method | Purpose |
|--------|---------|
| `invoke()` | Synchronous invocation with input processing |
| `ainvoke()` | Asynchronous invocation |
| `bind_tools()` | Attach tools/functions to the model for tool calling |
| `with_structured_output()` | Constrain output to follow a schema |
The `bind_tools` method enables models to call external tools, which is fundamental for building agentic applications:
```python
model = ChatOpenAI(model="gpt-4o-mini", temperature=0)
tools = toolkit.get_tools()
api_request_chain = API_URL_PROMPT.partial(api_docs=api_spec) | model.bind_tools(tools, tool_choice="any")
```
资料来源：[libs/langchain/langchain_classic/chains/api/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/chains/api/base.py)
### Message Types
Chat models in LangChain work with structured message objects that represent different roles in a conversation:
| Message Type | Role | Typical Use |
|--------------|------|-------------|
| `SystemMessage` | System | Instructions and context |
| `HumanMessage` | User | User input |
| `AIMessage` | Assistant | Model responses |
| `ToolMessage` | Tool | Tool execution results |
### State Management in Chat Applications
When building chat applications with stateful interactions, LangChain uses typed state dictionaries with LangGraph:
```python
class ChainState(TypedDict):
"""LangGraph state."""
messages: Annotated[Sequence[BaseMessage], add_messages]
async def acall_model(state: ChainState, config: RunnableConfig):
response = await model.ainvoke(state["messages"], config)
return {"messages": [response]}
```
资料来源：[libs/langchain/langchain_classic/chains/api/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/chains/api/base.py)
## Embeddings
### Embeddings Interface
The `Embeddings` interface provides a standardized way to convert text into numerical vector representations. These vectors enable semantic similarity calculations, retrieval-augmented generation (RAG), and vector database operations.
#### Core Methods
| Method | Description |
|--------|-------------|
| `embed_query()` | Embed a single query string |
| `embed_documents()` | Embed multiple document strings |
| `embed_query_async()` | Async version of embed_query |
| `embed_documents_async()` | Async version of embed_documents |
资料来源：[libs/core/langchain_core/embeddings/embeddings.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/embeddings/embeddings.py)
### Integration with Vector Stores
Embeddings work seamlessly with LangChain's vector store integrations. The HuggingFace partner package provides specific implementations:
```bash
# Install with full dependencies for local inference
pip install langchain-huggingface[full]
```
The `[full]` extra includes `sentence-transformers>=5.2.0` and `transformers>=5.0.0`, which are required for `HuggingFaceEmbeddings`.
资料来源：[libs/partners/huggingface/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/huggingface/README.md)
## Model Providers
LangChain provides partner packages for various LLM providers, each following consistent patterns for installation and usage:
| Provider | Package | Install Command |
|----------|---------|-----------------|
| OpenAI | `langchain-openai` | `pip install langchain-openai` |
| Anthropic | `langchain-anthropic` | `pip install langchain-anthropic` |
| Ollama | `langchain-ollama` | `pip install langchain-ollama` |
| HuggingFace | `langchain-huggingface` | `pip install langchain-huggingface` |
| Groq | `langchain-groq` | `pip install langchain-groq` |
| DeepSeek | `langchain-deepseek` | `pip install langchain-deepseek` |
| Perplexity | `langchain-perplexity` | `pip install langchain-perplexity` |
| xAI | `langchain-xai` | `pip install langchain-xai` |
| Chroma | `langchain-chroma` | `pip install langchain-chroma` |
| Exa | `langchain-exa` | `pip install langchain-exa` |
| OpenRouter | `langchain-openrouter` | `pip install langchain-openrouter` |
Each provider package contains integration classes that implement the base interfaces described above.
资料来源：[libs/partners/openai/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/openai/README.md), [libs/partners/anthropic/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/anthropic/README.md), [libs/partners/ollama/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/ollama/README.md)
## Testing Chat Models
LangChain provides standardized test infrastructure through the `langchain-tests` package to ensure consistent behavior across implementations:
```python
from typing import Type
import pytest
from langchain_core.language_models import BaseChatModel
from langchain_tests.unit_tests import ChatModelUnitTests
from langchain_parrot_chain import ChatParrotChain
class TestParrotChainStandard(ChatModelUnitTests):
@pytest.fixture
def chat_model_class(self) -> Type[BaseChatModel]:
return ChatParrotChain
```
#### Configurable Test Fixtures
| Fixture | Required | Default | Description |
|---------|----------|---------|-------------|
| `chat_model_class` | Yes | — | The chat model class to test |
| `chat_model_params` | No | `{}` | Constructor keyword arguments |
| `chat_model_has_tool_calling` | No | `hasattr(class, 'bind_tools')` | Tool calling capability |
| `chat_model_has_structured_output` | No | `hasattr(class, 'with_structured_output')` | Structured output support |
资料来源：[libs/standard-tests/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/standard-tests/README.md)
## Deprecated Patterns
The `langchain-community` package previously contained community-contributed integrations, but this pattern is being deprecated in favor of official partner packages:
```python
@deprecated(
since="0.2.13",
removal="2.0.0",
alternative="langchain.agents.create_agent",
)
class APIChain(Chain):
"""Chain that makes API calls and summarizes the responses."""
```
New integrations should be implemented as standalone partner packages following the patterns established in `libs/partners/*`.
资料来源：[libs/langchain/langchain_classic/chains/api/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/chains/api/base.py)
## Quick Reference
### Initialization
```python
from langchain.chat_models import init_chat_model
# Basic initialization
model = init_chat_model("provider:model-name")
# With parameters
model = init_chat_model("openai:gpt-4o-mini", temperature=0)
```
### Invocation
```python
# Synchronous
response = model.invoke("Your message here")
# Asynchronous
response = await model.ainvoke("Your message here")
# With chat history
response = model.invoke([SystemMessage(content="You are helpful"),
HumanMessage(content="Hello")])
```
### Tool Binding
```python
model_with_tools = model.bind_tools(tools)
response = model_with_tools.invoke("Use tool X to find information")
```
## Further Reading
- [API Reference](https://reference.langchain.com/python) - Complete API documentation
- [LangChain Docs](https://docs.langchain.com/oss/python/langchain/overview) - Conceptual guides and tutorials
- [LangGraph](https://docs.langchain.com/oss/python/langgraph/overview) - Building controllable agent workflows
- [Contributing Guide](https://docs.langchain.com/oss/python/contributing/overview) - How to add new integrations
---
## Agents Framework
### 相关页面
相关主题：[Tools and Toolkits](#tools-integrations), [Runnable and Execution Model](#runnable-execution)
相关源码文件
以下源码文件用于生成本页说明：
- [libs/langchain/langchain_classic/agents/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/__init__.py)
- [libs/langchain/langchain_classic/agents/agent.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/agent.py)
- [libs/langchain/langchain_classic/agents/react/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/react/__init__.py)
- [libs/langchain/langchain_classic/agents/structured_chat/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/structured_chat/__init__.py)
- [libs/langchain/langchain_classic/agents/openai_functions_agent/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/openai_functions_agent/__init__.py)
- [libs/langchain/langchain_classic/agents/agent_toolkits/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/agent_toolkits/__init__.py)
# Agents Framework
The LangChain Agents Framework is a core component of the LangChain ecosystem that enables language models to reason about and take actions through a systematic loop of observation, thought, and execution. The framework provides abstractions for building autonomous agents that can use tools, make decisions, and complete complex multi-step tasks.
## Architecture Overview
LangChain's agent architecture follows a cyclical pattern where the agent receives inputs, decides on actions using an LLM, executes those actions via tools, and processes the results to determine the next step.
```mermaid
graph TD
A[User Input] --> B[Agent]
B --> C[LLM Decision]
C --> D{Action Type}
D -->|Tool Call| E[Tool Execution]
D -->|Final Answer| F[Output]
E --> G[Observation]
G --> B
F --> H[User]
style B fill:#e1f5fe
style C fill:#fff3e0
style E fill:#f3e5f5
```
## Core Agent Classes
The agent system is built on a base `Agent` class that defines the interface for all agent implementations. LangChain provides several pre-built agent types for different use cases.
### Base Agent Interface
All agents inherit from the base `Agent` class which provides:
- Chain integration for LLM calls
- Tool binding and management
- Output parsing for action extraction
- State management across agent steps
### Agent Types
| Agent Type | Description | Use Case |
|------------|-------------|----------|
| `ReAct` | Reasoning + Acting agent | General purpose tool use |
| `Structured Chat` | JSON-structured tool calls | Structured tool interfaces |
| `OpenAI Functions` | OpenAI function calling format | OpenAI function calling |
| `Toolkits` | Pre-configured tool bundles | Domain-specific tasks |
资料来源：[libs/langchain/langchain_classic/agents/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/__init__.py)
## Tool Integration
Agents interact with external systems through tools. Tools are abstractions that wrap functionality and expose it to the LLM in a structured format.
### Tool Structure
Each tool typically consists of:
- **Name**: Unique identifier for the tool
- **Description**: Natural language description for LLM understanding
- **Parameters**: Schema defining required and optional inputs
- **Execute Function**: The actual implementation
### Toolkits
Toolkits provide pre-configured bundles of related tools for specific domains:
| Toolkit | Purpose |
|---------|---------|
| `RequestsToolkit` | HTTP requests for API interactions |
| `SQLDatabaseToolkit` | Database queries |
| Custom Toolkits | Domain-specific tool collections |
资料来源：[libs/langchain/langchain_classic/agents/agent_toolkits/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/agent_toolkits/__init__.py)
## Agent Execution Loop
The agent execution follows a ReAct-style (Reasoning + Acting) pattern:
```mermaid
sequenceDiagram
participant User
participant Agent
participant LLM
participant Tools
User->>Agent: Input Query
Agent->>LLM: Prompt + Tools
LLM-->>Agent: Thought + Action
Agent->>Tools: Execute Tool Call
Tools-->>Agent: Observation
Agent->>LLM: Observation + Next Decision
loop Until Final Answer
LLM-->>Agent: Next Action
Agent->>Tools: Execute Tool Call
Tools-->>Agent: Observation
end
Agent-->>User: Final Response
```
## Agent Creation API
The recommended way to create agents is through the `create_agent` factory function:
```python
from langchain.agents import create_agent
# Create an agent with specified model and tools
agent = create_agent(
model="openai:gpt-4",
tools=[...],
system_message="You are a helpful assistant."
)
```
资料来源：[libs/langchain/langchain_classic/agents/agent.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/agent.py)
## Agent Types Detail
### ReAct Agent
The ReAct (Reasoning + Acting) agent implements a reasoning loop where the model thinks through each step before taking action.
**Characteristics:**
- Explicit thought process before each action
- Observation processing after tool execution
- Flexible tool usage without strict schema requirements
资料来源：[libs/langchain/langchain_classic/agents/react/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/react/__init__.py)
### Structured Chat Agent
Designed for agents that interact with tools using structured JSON inputs, this agent type excels when working with tools that have complex parameter schemas.
**Characteristics:**
- JSON-structured tool inputs
- Strong typing for tool parameters
- Schema validation for tool calls
资料来源：[libs/langchain/langchain_classic/agents/structured_chat/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/structured_chat/__init__.py)
### OpenAI Functions Agent
Optimized for OpenAI's function calling API, this agent type maps LangChain tools to OpenAI function specifications.
**Characteristics:**
- Direct mapping to OpenAI function calling format
- Tool choice controls (auto, any, none)
- Streaming support for responses
资料来源：[libs/langchain/langchain_classic/agents/openai_functions_agent/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/agents/openai_functions_agent/__init__.py)
## Integration with LangGraph
For complex agent workflows, LangChain Agents integrate seamlessly with LangGraph for building stateful, controllable agent applications:
```python
from langgraph.prebuilt import ToolNode
from langgraph.graph import StateGraph
class AgentState(TypedDict):
messages: Annotated[Sequence[BaseMessage], add_messages]
graph_builder = StateGraph(AgentState)
graph_builder.add_node("call_tool", some_agent_node)
graph_builder.add_node("execute_tool", ToolNode(tools))
graph_builder.add_edge("call_tool", "execute_tool")
```
## Configuration Options
| Parameter | Type | Description |
|-----------|------|-------------|
| `model` | `str` or `BaseLanguageModel` | LLM to power the agent |
| `tools` | `List[BaseTool]` | Available tools for the agent |
| `system_message` | `str` | Instructions for agent behavior |
| `max_iterations` | `int` | Maximum agent steps before termination |
| `timeout` | `float` | Timeout for agent execution |
## Deprecated Patterns
The `APIChain` class has been deprecated in favor of the new agent system:
```python
@deprecated(
since="0.2.13",
removal="2.0.0",
alternative="langchain.agents.create_agent",
)
class APIChain(Chain):
"""Chain that makes API calls and summarizes responses."""
```
Migration to the new agent system is recommended for all use cases.
## Security Considerations
When deploying agents:
- **Input Validation**: Validate all user inputs before processing
- **Tool Permissions**: Control which tools are available to agents
- **Network Access**: Limit agent network capabilities appropriately
- **Rate Limiting**: Implement rate limiting to prevent abuse
## Summary
The LangChain Agents Framework provides a flexible, extensible system for building LLM-powered agents that can:
1. Reason about user queries
2. Select appropriate tools for task completion
3. Execute actions and process results
4. Iterate until goals are achieved
The framework supports multiple agent types optimized for different use cases, with seamless integration into the broader LangChain ecosystem including LangGraph for complex workflows.
---
## Tools and Toolkits
### 相关页面
相关主题：[Agents Framework](#agents-framework)
相关源码文件
以下源码文件用于生成本页说明：
- [libs/core/langchain_core/tools/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tools/__init__.py)
- [libs/core/langchain_core/tools/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tools/base.py)
- [libs/core/langchain_core/tools/structured.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tools/structured.py)
- [libs/core/langchain_core/tools/render.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tools/render.py)
- [libs/langchain/langchain_classic/tools/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/tools/__init__.py)
- [libs/langchain/langchain_classic/tools/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/tools/base.py)
# Tools and Toolkits
LangChain provides a flexible and extensible system for defining, managing, and executing tools that enable Large Language Models (LLMs) to interact with external systems, APIs, and data sources. The Tools and Toolkits module forms the foundational building block for agent-based architectures, allowing models to perform actions and retrieve information beyond their training data.
## Overview
Tools in LangChain serve as the interface between LLMs and external capabilities. They provide a standardized way to:
- Define callable functions with clear input/output schemas
- Control what operations an agent can perform
- Handle serialization, deserialization, and tool calling protocols
- Integrate with various third-party services and APIs
The system is designed around the principle of structured tool definitions, where each tool specifies its name, description, and parameter schema, enabling LLMs to understand when and how to invoke specific tools.
## Architecture
```mermaid
graph TD
A[Agent / LLM] -->|Tool Calls| B[Tool Executor]
B --> C[BaseTool]
C --> D[StructuredTool]
C --> E[ToolKit]
D --> F[Function Definition]
E --> G[Tool Collection]
B -->|Results| A
style A fill:#e1f5ff
style B fill:#fff3e0
style C fill:#e8f5e9
```
## Core Components
### BaseTool
The `BaseTool` class serves as the foundation for all tools in LangChain. It provides the essential interface that all tool implementations must follow.
| Attribute | Type | Description |
|-----------|------|-------------|
| `name` | `str` | Unique identifier for the tool |
| `description` | `str` | Human-readable description for LLM understanding |
| `args_schema` | `Type[BaseModel]` | Pydantic model defining input parameters |
| `return_schema` | `Optional[Type[BaseModel]]` | Schema for return values |
| `tags` | `Optional[List[str]]` | Categorization tags |
| `metadata` | `Optional[Dict[str, Any]]` | Additional metadata |
**Key Methods:**
```python
def invoke(self, input: Union[str, Dict], config: Optional[CallbackManager] = None) -> Any
async def ainvoke(self, input: Union[str, Dict], config: Optional[AsyncCallbackManager] = None) -> Any
```
资料来源：[libs/core/langchain_core/tools/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tools/base.py)
### StructuredTool
`StructuredTool` extends `BaseTool` with enhanced parameter handling capabilities. It supports complex input schemas and provides better type safety for tool definitions.
**Key Features:**
- Pydantic-based input validation
- JSON schema generation for LLM tool calling protocols
- Support for nested objects and arrays
- Custom validation logic via model validators
资料来源：[libs/core/langchain_core/tools/structured.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tools/structured.py)
## Tool Definition Pattern
```python
from langchain_core.tools import StructuredTool
from pydantic import BaseModel, Field
class SearchInput(BaseModel):
query: str = Field(description="The search query to look up")
limit: int = Field(default=10, description="Maximum number of results")
def search_function(query: str, limit: int = 10) -> str:
"""Perform a web search and return results."""
# Implementation here
pass
search_tool = StructuredTool(
name="web_search",
description="Search the web for information about a given topic",
func=search_function,
args_schema=SearchInput,
)
```
## Toolkits
Toolkits provide a convenient way to group related tools together. They bundle multiple tools that are commonly used together for specific use cases.
### Toolkit Structure
| Component | Description |
|-----------|-------------|
| `tools` | List of `BaseTool` instances |
| `name` | Toolkit identifier |
| `description` | Summary of toolkit purpose |
### Creating Custom Toolkits
```python
from langchain_core.tools import BaseTool, StructuredTool
from langchain_core.tools import Toolkit
class CustomToolkit(Toolkit):
def __init__(self) -> None:
super().__init__()
self.tools = [
tool_a,
tool_b,
tool_c,
]
def get_tools(self) -> list[BaseTool]:
return self.tools
```
资料来源：[libs/langchain/langchain_classic/tools/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/tools/base.py)
## Tool Rendering
Tool rendering converts tool definitions into formats consumable by different LLM providers and protocols.
```mermaid
graph LR
A[BaseTool] -->|convert| B[OpenAI Format]
A -->|convert| C[Anthropic Format]
A -->|convert| D[JSON Schema]
A -->|convert| E[Custom Format]
```
### Render Modes
| Mode | Description |
|------|-------------|
| `tool_call` | Renders tools for OpenAI-style tool calling |
| `json_schema` | Outputs JSON Schema representation |
| `anthropic` | Format compatible with Anthropic Claude models |
资料来源：[libs/core/langchain_core/tools/render.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/tools/render.py)
## Tool Execution Flow
```mermaid
sequenceDiagram
participant Agent
participant Executor
participant Tool
participant External
Agent->>Executor: invoke(tool_name, parameters)
Executor->>Tool: validate_and_bind_params(input)
Tool->>External: execute_action()
External-->>Tool: result
Tool-->>Executor: validated_result
Executor-->>Agent: ToolOutput
```
## Integration with Agents
Tools are bound to agents through the agent construction process. The binding specifies which tools an agent can access and how they should be invoked.
**Common Patterns:**
1. **Direct Binding**: Single tool passed to agent
2. **ToolKit Binding**: Multiple related tools from a toolkit
3. **Dynamic Binding**: Tools selected at runtime based on context
```python
from langchain.agents import create_agent
from langchain_core.tools import StructuredTool
agent = create_agent(
llm=model,
tools=[search_tool, calculator_tool],
prompt=system_prompt,
)
```
## Built-in Tool Categories
### Core Tools
Located in `libs/langchain/langchain_classic/tools/`:
| Tool | Purpose |
|------|---------|
| `Search` | Web search capabilities |
| `Wikipedia` | Wikipedia API integration |
| `Calculator` | Mathematical operations |
| `FileSystem` | Local file operations |
### API Integration Tools
LangChain provides specialized tools for API interactions:
```python
from langchain_classic.chains.api.base import APIChain
# APIChain is deprecated in favor of agent-based approaches
# but demonstrates the pattern of API tool integration
```
资料来源：[libs/langchain/langchain_classic/chains/api/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/chains/api/base.py)
## Configuration Options
### Tool Configuration Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `handle_parsing_errors` | `bool` | `True` | Handle LLM output parsing errors |
| `return_direct` | `bool` | `False` | Return tool output directly to LLM |
| `verbose` | `bool` | `False` | Enable verbose logging |
| `max_retries` | `int` | `3` | Maximum retry attempts |
| `timeout` | `Optional[float]` | `None` | Execution timeout in seconds |
## Error Handling
Tools implement comprehensive error handling to manage failures gracefully:
```python
try:
result = tool.invoke(input_dict)
except ValidationError as e:
# Handle input validation failures
return ErrorOutput(error=str(e))
except ExecutionError as e:
# Handle execution failures
return ErrorOutput(error=str(e))
except TimeoutError:
# Handle timeout
return ErrorOutput(error="Tool execution timed out")
```
## Best Practices
### 1. Clear Tool Descriptions
Write descriptions that help the LLM understand when and how to use each tool:
```python
description = """
Search for information on the web.
Use this tool when:
- User asks about current events or facts
- User requests information not in training data
- User asks about specific entities that need verification
Parameters:
- query: The search query (required)
- limit: Maximum results to return (optional, default: 5)
"""
```
### 2. Comprehensive Schemas
Define complete input schemas with descriptions:
```python
class QueryInput(BaseModel):
query: str = Field(
description="The search query string. Be specific and include relevant keywords.",
min_length=1,
max_length=500,
)
source: Literal["web", "news", "scholar"] = Field(
default="web",
description="The type of search to perform",
)
```
### 3. Proper Error Messages
Return meaningful error messages that help the agent recover:
```python
def execute_tool(self, params: Dict) -> str:
try:
return self._do_execution(params)
except ValueError as e:
return f"Invalid input: {str(e)}. Please check your parameters and try again."
except ConnectionError:
return "Unable to connect to the service. Please check your network connection."
```
## Testing Tools
LangChain provides testing utilities for tool implementations:
```python
from langchain_core.tools import tool, StructuredTool
def test_tool_invoke():
"""Test tool invocation with valid input."""
result = my_tool.invoke({"param1": "value1"})
assert result is not None
def test_tool_validation():
"""Test input validation."""
from pydantic import ValidationError
try:
my_tool.invoke({"invalid_param": "value"})
assert False, "Should have raised ValidationError"
except ValidationError:
pass # Expected behavior
```
## Package Structure
```
langchain/
├── libs/
│ ├── core/
│ │ └── langchain_core/
│ │ └── tools/
│ │ ├── __init__.py # Public API exports
│ │ ├── base.py # BaseTool implementation
│ │ ├── structured.py # StructuredTool implementation
│ │ └── render.py # Tool rendering utilities
│ └── langchain/
│ └── langchain_classic/
│ └── tools/
│ ├── __init__.py # Built-in tools
│ └── base.py # Toolkit base classes
```
## See Also
- [Agents Documentation](https://docs.langchain.com/oss/python/langchain/agents)
- [Chain Reference](https://docs.langchain.com/oss/python/langchain/chains)
- [Integration Providers](https://docs.langchain.com/oss/python/integrations/providers)
---
## Document Loaders and Text Processing
### 相关页面
相关主题：[Vector Stores and Retrievers](#vectorstores-retrievers), [Document Loaders and Text Processing](#document-loaders)
相关源码文件
以下源码文件用于生成本页说明：
- [libs/core/langchain_core/document_loaders/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/document_loaders/__init__.py)
- [libs/core/langchain_core/document_loaders/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/document_loaders/base.py)
- [libs/langchain/langchain_classic/document_loaders/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/document_loaders/__init__.py)
- [libs/langchain/langchain_classic/document_loaders/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/document_loaders/base.py)
- [libs/text-splitters/langchain_text_splitters/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/text-splitters/langchain_text_splitters/__init__.py)
- [libs/text-splitters/langchain_text_splitters/character.py](https://github.com/langchain-ai/langchain/blob/main/libs/text-splitters/langchain_text_splitters/character.py)
# Document Loaders and Text Processing
Document Loaders and Text Processing are fundamental components in the LangChain ecosystem that enable the ingestion, transformation, and preparation of various document types for downstream AI applications. These components form the entry point for most LLM-powered workflows, converting raw content from diverse sources into structured `Document` objects that can be processed by chains, agents, and retrieval systems.
The document processing pipeline in LangChain follows a two-stage approach: first, documents are loaded from external sources using specialized loaders; second, the loaded content is optionally split into smaller, semantically coherent chunks using text splitters. This separation of concerns allows for flexible composition and reuse across different application scenarios.
## Architecture Overview
LangChain's document processing architecture is distributed across multiple packages within the monorepo, with core abstractions defined in `langchain-core` and legacy implementations preserved in `langchain-classic`. Text splitting functionality is isolated in a dedicated `langchain-text-splitters` package to maintain separation of concerns and enable independent versioning.
The architecture employs a base class pattern where `BaseLoader` defines the interface contract that all concrete loader implementations must satisfy. This design enables polymorphic usage across different document sources while maintaining consistent behavior. The `BaseTransformer` abstraction extends this pattern for document transformation, and the `TextSplitter` hierarchy provides pluggable text chunking strategies.
```mermaid
graph TD
A[External Sources] --> B[Document Loaders]
B --> C[Document Objects]
C --> D[Text Splitters]
D --> E[Chunked Documents]
E --> F[Vector Stores]
E --> G[LLM Chains]
E --> H[Agents]
B1[BaseLoader] --> B2[File Loaders]
B1 --> B3[Web Loaders]
B1 --> B4[Database Loaders]
B1 --> B5[Cloud Storage Loaders]
D1[TextSplitter] --> D2[CharacterTextSplitter]
D1 --> D3[RecursiveCharacterTextSplitter]
D1 --> D4[LanguageSpecificSplitter]
```
## Document Object Model
At the heart of LangChain's document processing lies the `Document` data class, which provides a standardized representation for loaded content. Each `Document` instance encapsulates the actual text content along with associated metadata that describes the source, provenance, and any auxiliary information relevant to the content.
The `Document` class is defined in `langchain-core` and serves as the universal currency for document data throughout the LangChain ecosystem. This unified representation enables seamless interoperability between loaders, splitters, and consumers such as vector stores and language models.
### Document Class Structure
| Attribute | Type | Description |
|-----------|------|-------------|
| `page_content` | `str` | The actual text content of the document |
| `metadata` | `dict[str, Any]` | Associated metadata including source, page number, etc. |
| `type` | `str` | Document type identifier (optional) |
The metadata dictionary provides flexibility for storing arbitrary key-value pairs that describe the document's origin and characteristics. Common metadata fields include the source file path, URL, creation date, author, and any domain-specific attributes that may be useful for filtering or attribution.
## Base Loader Interface
The `BaseLoader` abstract class in `langchain_core.document_loaders.base` establishes the foundational interface that all document loaders must implement. This interface ensures consistency across the loader ecosystem while allowing each loader to handle the specifics of its target data source.
```mermaid
graph LR
A[load] --> B[Document List]
A1[aload] --> B
C[lazy_load] --> B
D[get_lazy_loaders] --> E[Generator]
style A fill:#90EE90
style A1 fill:#90EE90
style C fill:#90EE90
style D fill:#90EE90
```
### Core Loading Methods
| Method | Return Type | Description |
|--------|-------------|-------------|
| `load()` | `list[Document]` | Load all documents synchronously |
| `aload()` | `list[Document]` | Load all documents asynchronously |
| `lazy_load()` | `Iterator[Document]` | Lazily load documents one at a time |
| `get_lazy_loaders()` | `Generator[BaseLoader]` | Generate child loaders for partitioning |
The `lazy_load()` method provides a memory-efficient approach for processing large document collections by yielding documents one at a time rather than loading everything into memory simultaneously. This is particularly valuable when working with large file systems or extensive web crawls.
资料来源：[libs/core/langchain_core/document_loaders/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/document_loaders/base.py)
## Base Transformer Interface
The `BaseTransformer` abstract class extends the loading framework to support document transformation and enrichment. Transformers operate on already-loaded documents, applying processing operations such as filtering, annotation, or format conversion.
This abstraction is particularly useful for implementing cross-cutting concerns like content cleaning, metadata extraction, and format standardization that should be applied consistently across multiple loader types.
```mermaid
graph TD
A[Raw Documents] --> B[Transformer Pipeline]
B --> C[Transformed Documents]
B1[Metadata Enricher] --> B
B2[Content Cleaner] --> B
B3[Format Converter] --> B
```
## Text Splitters
Text splitters address the practical requirement of dividing large documents into smaller, manageable chunks that satisfy token limitations and enable efficient retrieval. The `TextSplitter` class hierarchy in `langchain-text-splitters` provides multiple strategies for document segmentation.
The splitting process operates by first breaking documents into character-level chunks, then optionally applying a secondary splitting step based on the specific text structure (such as markdown headers, code blocks, or natural language sentences). This hierarchical approach ensures that chunks respect semantic boundaries while maintaining the desired size constraints.
### Character Text Splitter
The `CharacterTextSplitter` provides the foundational character-based splitting implementation. It divides text at character boundaries, with configurable chunk size and overlap parameters to control the granularity and continuity between chunks.
资料来源：[libs/text-splitters/langchain_text_splitters/character.py](https://github.com/langchain-ai/langchain/blob/main/libs/text-splitters/langchain_text_splitters/character.py)
#### Key Configuration Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `separator` | `str` | `"\n\n"` | Character sequence used for splitting |
| `chunk_size` | `int` | `4000` | Maximum characters per chunk |
| `chunk_overlap` | `int` | `200` | Characters of overlap between chunks |
| `length_function` | `Callable` | `len` | Function to calculate text length |
| `is_separator_regex` | `bool` | `False` | Whether separator is a regex pattern |
The `chunk_overlap` parameter is particularly important for maintaining context continuity across chunk boundaries. By including overlapping content between adjacent chunks, downstream systems can retrieve relevant information that might span a boundary without losing critical context.
```mermaid
graph LR
A[Full Document] --> B[Chunk 1
chars 0-4000]
B --> C[Chunk 2
chars 3800-7800
200 char overlap]
C --> D[Chunk 3
chars 7600-11600
200 char overlap]
style B fill:#87CEEB
style C fill:#87CEEB
style D fill:#87CEEB
```
### Recursive Character Text Splitter
The `RecursiveCharacterTextSplitter` extends the basic character splitter with a multi-pass approach that attempts to split text at increasingly smaller delimiters if the initial split results in chunks exceeding the target size. This strategy preserves semantic coherence by preferring natural text boundaries such as paragraphs and sentences over arbitrary character cuts.
The splitter maintains an ordered list of separators that it attempts in sequence: double newlines for paragraphs, single newlines for line breaks, spaces for mid-sentence breaks, and finally individual characters as a last resort. This ordered approach ensures that chunks align with linguistic structures whenever possible.
### Splitting Methods
| Method | Parameters | Return Type | Description |
|--------|------------|-------------|-------------|
| `split_documents()` | `documents: list[Document]` | `list[Document]` | Split a list of Document objects |
| `split_text()` | `text: str` | `list[str]` | Split raw text into chunks |
| `create_documents()` | `texts: list[str]`, `metadatas?: list[dict]` | `list[Document]` | Create Document objects from texts |
资料来源：[libs/text-splitters/langchain_text_splitters/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/text-splitters/langchain_text_splitters/__init__.py)
## Document Loader Categories
The LangChain ecosystem encompasses a diverse collection of document loaders organized by their target data sources. These loaders are distributed across multiple packages, with community-contributed loaders maintained in the `langchain-community` package and select integrations maintained by the LangChain team in the `partners/` directory.
### File System Loaders
File system loaders handle documents stored locally or accessible through file protocols. Support extends to common formats including plain text, CSV, JSON, XML, Markdown, and various word processing formats. Binary formats such as PDFs and Office documents require additional dependencies that are installed as optional extras.
| Loader Category | Typical Extensions | Dependencies |
|-----------------|-------------------|--------------|
| Plain Text | `.txt`, `.text` | None |
| Structured Data | `.csv`, `.json`, `.xml` | Built-in libraries |
| Documents | `.pdf`, `.docx`, `.pptx` | Optional extras |
| Code | `.py`, `.js`, `.java`, etc. | Language-specific parsers |
### Web Loaders
Web loaders enable extraction of content from internet and intranet resources. These loaders handle HTTP requests, HTML parsing, and content extraction to produce clean document objects free of navigation elements and advertising content.
The `WebBaseLoader`, `PyMuPDFLoader`, and `PlaywrightLoader` represent common approaches to web content extraction, each offering different tradeoffs between speed, accuracy, and JavaScript rendering capabilities.
### Database Loaders
Database loaders connect to SQL and NoSQL databases to extract structured data and present it as documents. These loaders are essential for enterprise workflows that require accessing content stored in data warehouses, document databases, or traditional relational systems.
### Cloud Storage Loaders
Integration with major cloud storage providers enables loading documents from Amazon S3, Google Cloud Storage, and Azure Blob Storage. These loaders handle authentication, bucket navigation, and file streaming to support large-scale document ingestion pipelines.
## Integration with Retrieval Systems
Document loaders and text splitters form the foundation of Retrieval-Augmented Generation (RAG) pipelines. After documents are loaded and chunked, they are typically embedded using embedding models and stored in vector databases for similarity search.
```mermaid
graph TD
A[Documents] --> B[Loader]
B --> C[Document Objects]
C --> D[Text Splitter]
D --> E[Chunks]
E --> F[Embedding Model]
F --> G[Vector Store]
G --> H[Retrieval]
H --> I[LLM Response]
```
The chunk size and overlap parameters directly impact retrieval quality. Smaller chunks capture fine-grained concepts but may lack sufficient context, while larger chunks provide more context but may dilute the relevance of retrieved content. Tuning these parameters requires balancing the specific requirements of the target application.
## Legacy and Deprecated Components
The `langchain-classic` package preserves legacy loader implementations that were present in earlier versions of LangChain. These components are maintained for backward compatibility but may lack features present in the newer `langchain-core` implementations.
资料来源：[libs/langchain/langchain_classic/document_loaders/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/document_loaders/__init__.py)
The deprecation warnings in `langchain-classic` indicate a gradual migration path toward the consolidated abstractions in `langchain-core`. New projects should prefer the core implementations, while existing projects can continue using classic loaders until suitable migration paths are available.
## Best Practices
When working with document loaders and text splitters, several practices help ensure optimal results in production environments. First, always consider the downstream consumer when selecting chunk sizes—smaller chunks work well for question answering, while larger chunks preserve more context for summarization tasks. Second, include comprehensive metadata during loading to enable filtering and attribution in later stages.
For large-scale document processing, prefer lazy loading strategies to manage memory consumption effectively. When dealing with heterogeneous document collections, consider creating custom transformer pipelines that apply format-specific preprocessing before the generic splitting logic.
The separator configuration should align with the natural structure of the document format. Markdown documents benefit from separator patterns that respect heading hierarchies, while plain text may work better with paragraph-based or sentence-based splitting strategies.
## Package Organization Summary
| Package | Purpose | Key Classes |
|---------|---------|-------------|
| `langchain-core` | Core abstractions | `BaseLoader`, `BaseTransformer`, `Document` |
| `langchain-classic` | Legacy implementations | `CSVLoader`, `PyPDFLoader`, etc. |
| `langchain-text-splitters` | Text chunking | `TextSplitter`, `CharacterTextSplitter`, `RecursiveCharacterTextSplitter` |
资料来源：[libs/core/langchain_core/document_loaders/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/document_loaders/__init__.py)
The separation of `langchain-text-splitters` into its own package reflects the independent applicability of text splitting beyond document loading. This design enables reuse of splitting logic in contexts where documents are generated programmatically or obtained through means other than loaders.
---
## Vector Stores and Retrievers
### 相关页面
相关主题：[Document Loaders and Text Processing](#document-loaders), [Chat Models and Embeddings](#chat-models-embeddings), [Tools and Toolkits](#tools-integrations)
相关源码文件
以下源码文件用于生成本页说明：
- [libs/core/langchain_core/vectorstores/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/vectorstores/__init__.py)
- [libs/core/langchain_core/vectorstores/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/core/langchain_core/vectorstores/base.py)
- [libs/langchain/langchain_classic/vectorstores/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/vectorstores/__init__.py)
- [libs/langchain/langchain_classic/vectorstores/base.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/vectorstores/base.py)
- [libs/langchain/langchain_classic/retrievers/__init__.py](https://github.com/langchain-ai/langchain/blob/main/libs/langchain/langchain_classic/retrievers/__init__.py)
- [libs/partners/chroma/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/chroma/README.md)
- [libs/partners/huggingface/README.md](https://github.com/langchain-ai/langchain/blob/main/libs/partners/huggingface/README.md)
# Vector Stores and Retrievers
## Overview
Vector Stores and Retrievers are fundamental components in LangChain that enable efficient similarity search and retrieval of documents based on semantic meaning. Vector stores handle the storage and indexing of embedded data, while retrievers provide the interface for querying and fetching relevant information from these stores.
LangChain provides a layered architecture where core abstractions are defined in `langchain_core` and concrete implementations are available through partner packages and `langchain_classic`.
## Architecture
The Vector Stores and Retrievers system follows a clean separation of concerns with interfaces defined at the core level and implementations distributed across the ecosystem.
```mermaid
graph TD
A[User Query] --> B[Embedding Model]
B --> C[Vector Query]
C --> D[Vector Store]
D --> E[Retriever]
E --> F[Retrieved Documents]
G[Documents] --> H[Document Loader]
H --> I[Text Splitter]
I --> J[Embedding Model]
J --> K[Indexed Vectors]
K --> D
L[langchain_core] --> M[BaseVectorStore Interface]
L --> N[BaseRetriever Interface]
O[langchain_classic] --> P[Additional VectorStore Implementations]
O --> Q[Retrievers]
R[Partner Packages] --> S[Chroma, FAISS, Pinecone, etc.]
```
## Vector Stores
### Core Interface
The base vector store interface in `langchain_core` provides the foundational methods that all vector store implementations must support. The interface is designed to be provider-agnostic while enabling specific features through optional methods.
#### Key Methods
| Method | Purpose | Parameters | Return Type |
|--------|---------|------------|-------------|
| `add_documents` | Add documents to the store | `documents: List[Document]`, `ids: Optional[List[str]]` | `List[str]` |
| `add_texts` | Add raw texts to the store | `texts: List[str]`, `metadatas: Optional[List[dict]]`, `ids: Optional[List[str]]` | `List[str]` |
| `similarity_search` | Find similar documents | `query: str`, `k: int`, `filter: Optional[dict]` | `List[Document]` |
| `similarity_search_by_vector` | Search by embedding | `embedding: List[float]`, `k: int`, `filter: Optional[dict]` | `List[Document]` |
| `similarity_search_with_score` | Search with relevance scores | `query: str`, `k: int`, `filter: Optional[dict]` | `List[Tuple[Document, float]]` |
| `delete` | Remove documents by ID | `ids: Optional[List[str]]` | `None` |
| `get_by_prefix` | Retrieve by ID prefix | `prefix: str` | `List[Document]` |
### Embeddings Integration
Vector stores work in conjunction with embedding models to convert text into vector representations. The HuggingFace integration provides `HuggingFaceEmbeddings` for generating embeddings locally:
```python
# From libs/partners/huggingface/README.md
from langchain_huggingface import HuggingFaceEmbeddings
# Requires sentence-transformers>=5.2.0
embeddings = HuggingFaceEmbeddings(model_name="all-MiniLM-L6-v2")
```
The embedding models are decoupled from vector stores, allowing flexibility in choosing both components independently.
### Deletion and Prefix Operations
Vector stores support flexible document management through deletion and prefix-based retrieval operations:
| Operation | Description |
|-----------|-------------|
| `delete(ids)` | Removes specific documents by their IDs |
| `get_by_prefix(prefix)` | Retrieves all documents whose IDs start with the given prefix |
These operations enable efficient document lifecycle management within the vector store.
## Retrievers
Retrievers provide a standardized interface for fetching relevant documents from various sources. They abstract away the underlying storage mechanism and provide additional capabilities like filtering and reranking.
### Base Retriever Interface
The retriever interface in `langchain_classic` defines the contract for all retrieval implementations:
```mermaid
graph LR
A[Query] --> B[Retriever]
B --> C{Filtering}
C -->|Apply| D[Metadata Filter]
C -->|Apply| E[Time-based Filter]
B --> F[Document Pool]
F --> G[Top-K Results]
```
### Retriever Types
LangChain provides several specialized retrievers:
| Retriever Type | Purpose | Use Case |
|----------------|---------|----------|
| `VectorStoreRetriever` | Standard similarity search | General-purpose retrieval |
| `MultiVectorRetriever` | Multiple embedding per document | Tables, images, sub-documents |
| `MultiQueryRetriever` | Generate multiple query variations | Improve recall |
| `ContextualCompressionRetriever` | Compress retrieved context | Reduce token usage |
| `TimeWeightedVectorStoreRetriever` | Prioritize recent documents | Recency-aware search |
### Configuration Options
Retrievers support various configuration parameters:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `search_type` | `str` | `"similarity"` | Search algorithm: `similarity`, `mmr` |
| `k` | `int` | `4` | Number of documents to retrieve |
| `fetch_k` | `int` | `20` | Initial pool size for MMR |
| `lambda_mult` | `float` | `0.5` | MMR diversity parameter |
| `filter` | `dict` | `None` | Metadata filter conditions |
## Partner Integrations
### Chroma Vector Store
The `langchain-chroma` package provides integration with Chroma, an open-source embedding database:
```bash
pip install langchain-chroma
```
Chroma is designed specifically for AI applications and provides efficient storage and retrieval of embeddings with metadata filtering capabilities.
### HuggingFace Embeddings
The `langchain-huggingface` package offers multiple embedding options:
- `HuggingFaceEmbeddings` - For local inference using sentence-transformers
- `HuggingFacePipeline` - For local LLM inference
For full functionality including embeddings:
```bash
pip install langchain-huggingface[full]
```
> **Note:** The `[full]` extra requires `sentence-transformers>=5.2.0` and `transformers>=5.0.0`. Projects migrating from `langchain-community` may need to upgrade `sentence-transformers` to `>=5.2.0`.
## Package Structure
### Core Layer (`langchain_core`)
The `langchain_core.vectorstores` module provides base abstractions that define the contract for all vector store implementations. This layer is dependency-light and focuses on interface definitions.
### Classic Layer (`langchain_classic`)
The `langchain_classic.vectorstores` module extends the core abstractions with additional functionality:
- Additional vector store implementations
- Utility functions for common operations
- Integration with other LangChain components
### Partner Packages
Partner packages provide maintained integrations with specific vector store providers:
```
libs/partners/
├── chroma/ # Chroma vector store
├── weaviate/ # Weaviate vector database
├── pinecone/ # Pinecone managed vector database
├── qdrant/ # Qdrant vector search engine
└── ... # Additional providers
```
## Workflow: Document Indexing and Retrieval
```mermaid
sequenceDiagram
participant User
participant Loader
participant Splitter
participant Embedder
participant VectorStore
participant Retriever
User->>Loader: Load documents
Loader-->>User: Raw documents
User->>Splitter: Split documents
Splitter-->>User: Chunked documents
User->>Embedder: Generate embeddings
Embedder-->>User: Vector embeddings
User->>VectorStore: Add documents + embeddings
VectorStore-->>User: Document IDs
User->>Retriever: Query
Retriever->>Embedder: Embed query
Embedder-->>Retriever: Query vector
Retriever->>VectorStore: Similarity search
VectorStore-->>Retriever: Top-K documents
Retriever-->>User: Retrieved results
```
## Best Practices
### Indexing Recommendations
1. **Chunk Size Selection**: Choose appropriate chunk sizes based on your use case—smaller chunks for precise retrieval, larger chunks for more context
2. **Metadata Enrichment**: Include relevant metadata during indexing to enable filtered retrieval
3. **Embedding Selection**: Match embedding models to your data type and language requirements
### Retrieval Optimization
1. **Use MMR for Diversity**: When using MMR (Maximal Marginal Relevance), tune `lambda_mult` to balance relevance and diversity
2. **Implement Filtering**: Use metadata filtering to narrow results to relevant subsets
3. **Consider Compression**: For long contexts, use contextual compression to reduce token usage
## Security Considerations
When implementing vector stores and retrievers in production:
- **Data Isolation**: Ensure vector store data is properly isolated based on access requirements
- **Input Sanitization**: Validate and sanitize query inputs to prevent injection attacks
- **Access Control**: Implement appropriate access controls for sensitive document retrieval
## See Also
- [LangChain Core Documentation](https://reference.langchain.com/python/langchain_core)
- [API Reference](https://reference.langchain.com/python/integrations/)
- [LangChain Docs](https://docs.langchain.com/oss/python/integrations/providers)
- [Partner Integrations](https://docs.langchain.com/oss/python/integrations/providers)
---
---
## Doramagic 踩坑日志
项目：langchain-ai/langchain
摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。
## 1. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:552661142 | https://github.com/langchain-ai/langchain | README/documentation is current enough for a first validation pass.
## 2. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:552661142 | https://github.com/langchain-ai/langchain | last_activity_observed missing
## 3. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:552661142 | https://github.com/langchain-ai/langchain | no_demo; severity=medium
## 4. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:552661142 | https://github.com/langchain-ai/langchain | no_demo; severity=medium
## 5. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:552661142 | https://github.com/langchain-ai/langchain | issue_or_pr_quality=unknown
## 6. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:552661142 | https://github.com/langchain-ai/langchain | release_recency=unknown