# https://github.com/stanfordnlp/dspy 项目说明书
生成时间：2026-05-17 06:56:43 UTC
## 目录
- [Introduction to DSPy](#introduction)
- [Installation and Setup](#installation)
- [Core Architecture](#core-architecture)
- [Signatures System](#signatures)
- [Module System](#modules)
- [Adapters](#adapters)
- [Language Model Clients](#lm-clients)
- [Prediction Modules](#predict-modules)
- [Agent Modules](#agent-modules)
- [Optimizers (Teleprompt)](#optimizers)
## Introduction to DSPy
### 相关页面
相关主题：[Installation and Setup](#installation), [Core Architecture](#core-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/stanfordnlp/dspy/blob/main/README.md)
- [dspy/primitives/example.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/example.py)
- [dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
- [dspy/clients/embedding.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/embedding.py)
- [dspy/adapters/types/document.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/types/document.py)
- [dspy/adapters/types/history.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/types/history.py)
# Introduction to DSPy
DSPy (Declarative Self-Improving Language Model Programs) is a framework for building and optimizing LLM-based pipelines. It provides a systematic approach to compiling declarative module calls into self-improving pipelines that can automatically optimize prompts and weights.
资料来源：[README.md:1]()
## Core Philosophy
DSPy abstracts away the complexity of prompt engineering by allowing developers to define programs as modules with signatures rather than manually crafting prompts. The framework then automatically optimizes how these modules interact to achieve better performance.
```mermaid
graph TD
A[User Defined Program] --> B[DSPy Signatures]
B --> C[DSPy Modules]
C --> D[Optimizer Compilation]
D --> E[Optimized Pipeline]
E --> F[Better Results]
```
资料来源：[dspy/primitives/module.py:1-50]()
## Key Concepts
### Signatures
Signatures define the input-output schema for modules. They specify which fields are inputs and which are outputs using `InputField` and `OutputField` decorators.
```python
class MySignature(dspy.Signature):
input_text: str = dspy.InputField(desc="Input sentence")
output_text: str = dspy.OutputField(desc="Translated sentence")
```
资料来源：[dspy/signatures/signature.py:1-30]()
### Modules
All DSPy programs inherit from `dspy.Module`, which provides methods for managing predictors and configuring language models.
| Method | Description |
|--------|-------------|
| `forward()` | Define the program's logic |
| `named_predictors()` | Get all Predict modules with names |
| `predictors()` | Get all Predict modules |
| `set_lm(lm)` | Set language model for all predictors |
| `get_lm()` | Retrieve the configured language model |
资料来源：[dspy/primitives/module.py:50-100]()
### Examples
The `Example` class represents data records used for training and evaluation. It supports input/label separation and dictionary-like access.
```python
example = dspy.Example(question="What is 2+2?", answer="4").with_inputs("question")
```
| Method | Purpose |
|--------|---------|
| `with_inputs(*keys)` | Mark fields as inputs |
| `inputs()` | Get only input fields |
| `labels()` | Get only label fields |
| `toDict()` | Convert to JSON-friendly dict |
| `get(key, default)` | Dictionary-style access |
资料来源：[dspy/primitives/example.py:1-100]()
### Predict
`Predict` is the core module that generates completions based on a signature. It can be configured with or without chain-of-thought reasoning.
```python
predictor = dspy.Predict("question -> answer")
predictor = dspy.ChainOfThought("question -> answer")
```
资料来源：[dspy/primitives/module.py:80-120]()
## Installation
### Standard Installation
```bash
pip install dspy
```
### Development Installation
For the latest features from the main branch:
```bash
pip install git+https://github.com/stanfordnlp/dspy.git
```
资料来源：[README.md:5-12]()
### Development Environment Setup
Python 3.10 or later is required. The recommended setup uses `uv`:
```shell
uv venv --python 3.10
uv sync --extra dev
```
Run tests with:
```shell
uv run pytest tests/predict
```
资料来源：[CONTRIBUTING.md:40-80]()
## Basic Usage Pattern
```mermaid
graph LR
A[Define Signature] --> B[Create Module]
B --> C[Configure LM]
C --> D[Compile with Optimizer]
D --> E[Run Program]
```
### Step 1: Define a Signature
```python
class QA(dspy.Signature):
"""Answer questions based on the context."""
context: str = dspy.InputField(desc="Context for answering")
question: str = dspy.InputField(desc="Question to answer")
answer: str = dspy.OutputField(desc="Answer to the question")
```
### Step 2: Build a Module
```python
class RAG(dspy.Module):
def __init__(self):
super().__init__()
self.retrieve = dspy.Retrieve(k=3)
self.qa = dspy.Predict(QA)
def forward(self, question):
context = self.retrieve(question).passages
return self.qa(context=context, question=question)
```
### Step 3: Configure Language Model
```python
lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)
```
### Step 4: Compile and Run
```python
compiled_rag = dspy.compile(RAG(), trainset=trainset, metric=metric)
result = compiled_rag(question="What is DSPy?")
```
## Supported Data Types
DSPy provides specialized types for common LLM use cases:
| Type | Purpose |
|------|---------|
| `Document` | Text content with title and citations support |
| `History` | Conversation history for multi-turn interactions |
| `Image` | Image inputs with URL/base64 encoding |
| `Citations` | Citation metadata from models |
### Document
```python
doc = Document(
data="The Earth orbits the Sun.",
title="Basic Astronomy Facts"
)
```
资料来源：[dspy/adapters/types/document.py:1-50]()
### History
```python
history = History(messages=[
{"question": "What is the capital of France?", "answer": "Paris"},
])
```
资料来源：[dspy/adapters/types/history.py:1-50]()
## Embedding Support
The `Embedder` class provides a unified interface for embedding models:
```python
embedder = dspy.Embedder("openai/text-embedding-3-small")
embeddings = embedder(["hello", "world"], batch_size=1)
```
Configuration options:
| Parameter | Default | Description |
|-----------|---------|-------------|
| `model` | Required | Embedding model name or callable |
| `batch_size` | 200 | Number of texts per batch |
| `caching` | True | Enable result caching |
资料来源：[dspy/clients/embedding.py:1-60]()
## Teleprompters and Optimization
DSPy includes teleprompters that automatically optimize prompts and weights:
```python
optimizer = BootstrapFewShotWithRandomSearch(metric=metric)
compiled_program = optimizer.compile(student=student_program, trainset=trainset)
```
Available optimizers include:
- `BootstrapFewShotWithRandomSearch` - Bootstrap demonstrations with random search
- `BootstrapFinetune` - Fine-tune weights on bootstrapped data
- `GEPA` - Reflective prompt evolution
- `BetterTogether` - Combined prompt + weight optimization
资料来源：[dspy/teleprompt/bettertogether.py:1-50]()
## Architecture Overview
```mermaid
graph TD
subgraph "User Layer"
A[User Program]
B[Signatures]
C[Examples]
end
subgraph "Core Layer"
D[Module]
E[Predict]
F[ChainOfThought]
G[Retrieve]
end
subgraph "Optimization Layer"
H[Teleprompters]
I[Proposers]
J[Metrics]
end
subgraph "Adapter Layer"
K[Document]
L[History]
M[Image]
N[Citations]
end
subgraph "Client Layer"
O[LM Client]
P[Embedding Client]
Q[Retriever Clients]
end
A --> D
B --> D
C --> H
D --> E
E --> H
H --> I
K --> O
L --> O
M --> O
N --> O
O --> P
O --> Q
```
## Citation
If you use DSPy in your research, please cite:
> **[Oct'23] [DSPy: Compiling Declarative Language Model Calls into Self-Improving Pipelines](https://arxiv.org/abs/2310.03714)**
资料来源：[README.md:20-30]()
## Documentation and Resources
For comprehensive documentation, visit the [DSPy Docs at dspy.ai](https://dspy.ai).
### Research Papers
| Paper | Date | Description |
|-------|------|-------------|
| GEPA: Reflective Prompt Evolution | Jul'25 | Alternative to RL |
| Optimizing Instructions and Demonstrations | Jun'24 | Multi-stage optimization |
| DSPy: Compiling Declarative LM Calls | Oct'23 | Core framework paper |
| Fine-Tuning and Prompt Optimization | Jul'24 | Joint optimization |
| Prompts as Auto-Optimized Training Hyperparameters | Jun'24 | Hyperparameter analogy |
资料来源：[README.md:15-35]()
---
## Installation and Setup
### 相关页面
相关主题：[Introduction to DSPy](#introduction), [Language Model Clients](#lm-clients)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/stanfordnlp/dspy/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/stanfordnlp/dspy/blob/main/CONTRIBUTING.md)
- [pyproject.toml](https://github.com/stanfordnlp/dspy/blob/main/pyproject.toml)
# Installation and Setup
This page covers how to install DSPy and configure your development environment for working with the framework.
## Overview
DSPy (Declarative Self-Improving Language Model Programs) is a Python framework that compiles declarative language model calls into self-improving pipelines. The installation process supports both end-user usage via pip and contributor workflows with advanced development tools. 资料来源：[README.md]()
## Prerequisites
### System Requirements
| Requirement | Minimum | Recommended |
|-------------|---------|-------------|
| Python Version | 3.10 | 3.11 or later |
| Operating System | Linux, macOS, Windows | Linux/macOS |
| Package Manager | pip | uv (Rust-based) |
资料来源：[CONTRIBUTING.md]()
## Basic Installation
### Installing from PyPI
The simplest way to install DSPy is using pip:
```bash
pip install dspy
```
资料来源：[README.md]()
### Installing from Source
To install the latest development version from the main branch:
```bash
pip install git+https://github.com/stanfordnlp/dspy.git
```
This approach installs the most up-to-date code that may include features not yet released to PyPI.
资料来源：[README.md]()
## Development Environment Setup
For contributors who want to modify DSPy or run tests, a development environment setup is required.
### Fork and Clone
First, fork the repository on GitHub, then clone your fork locally:
```shell
git clone {url-to-your-fork}
cd dspy
```
资料来源：[CONTRIBUTING.md]()
### Using uv (Recommended)
[uv](https://github.com/astral-sh/uv) is a Rust-based Python package and project manager that provides fast dependency resolution and virtual environment management.
#### Installation of uv
Follow the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) to install uv on your system.
#### Environment Creation
Create a virtual environment using Python 3.10:
```shell
uv venv --python 3.10
```
This creates a `.venv` directory in your project root.
#### Dependency Synchronization
Sync the environment with development dependencies:
```shell
uv sync --extra dev
```
#### Verification
Run unit tests to verify the setup:
```shell
uv run pytest tests/predict
```
资料来源：[CONTRIBUTING.md]()
### Using conda + pip
An alternative approach using conda and pip is available for users who prefer this workflow.
#### Environment Creation
```shell
conda create -n dspy-dev python=3.10
conda activate dspy-dev
```
#### Package Installation
```shell
pip install -e ".[dev]"
```
The `-e` flag installs the package in editable mode, allowing code changes to take effect without reinstallation.
#### Verification
```shell
pytest tests/predict
```
资料来源：[CONTRIBUTING.md]()
## Environment Management Patterns
### Using uv run
The `uv run` prefix must be used for every Python command when using the uv-managed environment:
| Action | Command |
|--------|---------|
| Run tests | `uv run pytest tests/predict` |
| Execute script | `uv run python script.py` |
| Install package | `uv run pip install package-name` |
资料来源：[CONTRIBUTING.md]()
### Development Workflow
```mermaid
graph TD
A[Fork Repository] --> B[Clone Your Fork]
B --> C[Install uv]
C --> D[Create venv with Python 3.10]
D --> E[Sync dependencies with dev extras]
E --> F[Run tests to verify]
F --> G[Start development]
G --> H[Make changes]
H --> I[Commit changes]
I --> J[Push to fork]
J --> K[Create Pull Request]
```
## Project Configuration
### pyproject.toml Structure
The project uses `pyproject.toml` for dependency management and package configuration. Key sections include:
- **build-system**: Build backend configuration
- **project**: Core dependencies and project metadata
- **project.optional-dependencies**: Extra dependencies for different features (dev, etc.)
资料来源：[pyproject.toml]()
## Pre-commit Hooks
DSPy uses pre-commit hooks to maintain code quality. After installing dependencies, hooks are automatically installed but need to be staged and committed along with your changes.
### Running Hooks Manually
| Command | Purpose |
|---------|---------|
| `pre-commit run` | Check all staged files |
| `pre-commit run --files path/to/file.py` | Check specific files |
All pre-commit checks must pass before creating a pull request. You can commit changes and let hooks fix formatting issues automatically.
资料来源：[CONTRIBUTING.md]()
## Verification Checklist
After completing installation, verify your setup by checking:
1. Python version: `python --version` (should be 3.10+)
2. DSPy import: `python -c "import dspy; print(dspy.__version__)"`
3. Running basic tests: `uv run pytest tests/predict -v`
## Next Steps
After successful installation and setup:
- Review the [DSPy documentation](https://dspy.ai) for framework concepts
- Explore the signature system for defining module inputs/outputs
- Set up your language model configuration
- Try the teleprompters for prompt optimization
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| Python version too old | Upgrade to Python 3.10 or later |
| uv command not found | Install uv following the official guide |
| Tests fail after install | Ensure dependencies are fully synced with `uv sync --extra dev` |
| Pre-commit hooks not running | Run `pre-commit install` to enable hooks |
## Related Documentation
- [DSPy Official Docs](https://dspy.ai)
- [GitHub Repository](https://github.com/stanfordnlp/dspy)
- [Research Papers](https://github.com/stanfordnlp/dspy#-citation-reading-more)
---
## Core Architecture
### 相关页面
相关主题：[Signatures System](#signatures), [Module System](#modules)
相关源码文件
以下源码文件用于生成本页说明：
- [dspy/primitives/example.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/example.py)
- [dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
- [dspy/clients/embedding.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/embedding.py)
- [dspy/predict/rlm.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/rlm.py)
- [dspy/utils/callback.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/utils/callback.py)
# Core Architecture
The DSPy framework's core architecture provides the foundational building blocks for composing, executing, and optimizing language model programs. At its heart, DSPy separates the concerns of **program structure**, **data representation**, and **model interaction** into distinct but interconnected components.
## Architecture Overview
DSPy's core architecture follows a layered design where higher-level abstractions build upon primitive components. The primitives module (`dspy/primitives/`) contains the essential classes that define how programs are structured, how data flows through them, and how outputs are represented.
```mermaid
graph TD
subgraph "Core Primitives"
Example[Example
Data Container]
Module[Module
Program Base]
Prediction[Prediction
Output Container]
end
subgraph "Language Model Layer"
LM[Language Model
Client]
Embedder[Embedder
Embedding Client]
end
subgraph "Program Layer"
Predict[Predict Module]
CoT[ChainOfThought]
RLM[RLM Module]
end
Example -->|Defines I/O| Module
Module -->|Executes via| LM
LM -->|Produces| Prediction
Predict -->|Uses| Module
RLM -->|Extends| Module
```
## Data Model Layer
### The `Example` Class
The `Example` class serves as DSPy's primary data structure for representing training examples, test cases, and evaluation samples. It wraps a dictionary-based storage (`_store`) and maintains metadata about which fields are inputs versus labels.
**Key Characteristics:**
| Attribute | Type | Purpose |
|-----------|------|---------|
| `_store` | `dict` | Internal storage for field names and values |
| `_input_keys` | `set[str] \| None` | Tracks which fields are inputs |
**Core Methods:**
| Method | Purpose |
|--------|---------|
| `with_inputs(*keys)` | Marks specified fields as input fields |
| `inputs()` | Returns a new Example containing only input fields |
| `labels()` | Returns a new Example containing only non-input (label) fields |
| `toDict()` | Recursively serializes the Example to a JSON-friendly dict |
| `copy()` | Creates a shallow copy with optional field overrides |
| `get(key, default)` | Retrieves a field value with optional default |
| `keys()`, `values()`, `items()` | Dictionary-like access methods |
资料来源：[dspy/primitives/example.py:1-50]()
**Usage Pattern:**
```python
# Create an example with question-answer pairs
example = dspy.Example(
question="What is the capital of France?",
answer="Paris"
).with_inputs("question")
# Access inputs and labels separately
example.inputs() # Example({'question': '...'})
example.labels() # Example({'answer': '...'})
# Convert to dictionary for serialization
example.toDict() # {'question': '...', 'answer': '...'}
```
The `toDict()` method handles nested objects by recursively converting `Example` objects, Pydantic models, lists, and dicts to JSON-friendly structures.
资料来源：[dspy/primitives/example.py:1-30]()
### The `Prediction` Class
The `Prediction` class represents the output of a DSPy program execution. It encapsulates the results produced by language model calls, typically containing fields that correspond to the output fields defined in a signature.
## Program Structure Layer
### The `Module` Class
The `Module` class is the fundamental base class from which all DSPy programs inherit. It provides the runtime infrastructure for composing language model calls, managing parameters, and executing programs.
**Key Methods:**
| Method | Returns | Description |
|--------|---------|-------------|
| `named_predictors()` | `list[tuple[str, Predict]]` | Returns all Predict modules with their attribute names |
| `predictors()` | `list[Predict]` | Returns only the Predict module instances |
| `set_lm(lm)` | `None` | Recursively sets the language model for all contained Predict modules |
| `get_lm()` | `LM` | Returns the language model if all predictors share the same LM |
资料来源：[dspy/primitives/module.py:1-60]()
**Predictor Discovery:**
The `named_predictors()` method uses introspection to find all `Predict` instances within a module:
```python
class MyProgram(dspy.Module):
def __init__(self):
super().__init__()
self.qa = dspy.Predict("question -> answer")
self.summarize = dspy.Predict("text -> summary")
program = MyProgram()
for name, predictor in program.named_predictors():
print(name) # 'qa', 'summarize'
```
资料来源：[dspy/primitives/module.py:1-45]()
### Language Model Integration
The `set_lm()` method traverses the module's parameter tree to attach a language model to every `Predict` instance:
```python
lm = dspy.LM("openai/gpt-4o-mini")
program.set_lm(lm)
```
This recursive propagation ensures that nested modules and chained predictors all share the same language model configuration.
资料来源：[dspy/primitives/module.py:45-55]()
## Execution Flow
```mermaid
sequenceDiagram
participant User
participant Module
participant Predict
participant LM
participant Prediction
User->>Module: forward(**inputs)
Module->>Predict: forward(**inputs)
Predict->>LM: generate(input_fields, signature)
LM-->>Predict: raw_output
Predict->>Prediction: format(raw_output, signature)
Prediction-->>Module: Prediction object
Module-->>User: Program output
Note over Predict: Validates and transforms
LM output according
to Signature fields
```
## Signature-Based Input/Output Contract
DSPy programs use **Signatures** to define the contract between modules and language models. A signature specifies input fields and output fields, along with optional descriptions that guide the LM's behavior.
The `Signature.with_updated_fields()` method allows runtime modification of field metadata:
```python
NewSig = MySig.with_updated_fields(
"output_text",
desc="The translated French text"
)
```
资料来源：[dspy/signatures/signature.py:1-40]()
## Extended Modules
### RLM (Recursive Language Model)
The `RLM` class extends the base `Module` to provide sandboxed REPL-based code execution capabilities, enabling LLMs to programmatically explore large contexts through Python code:
```python
rlm = RLM(
sandbox="python", # or "bash"
timeout=30
)
```
资料来源：[dspy/predict/rlm.py:1-30]()
### Embedder
The `Embedder` class provides a consistent interface for embedding generation with built-in batching and caching:
```python
embedder = dspy.Embedder(
model="openai/text-embedding-3-small",
batch_size=200,
caching=True
)
```
资料来源：[dspy/clients/embedding.py:1-50]()
## Callback System
DSPy's callback system (`dspy/utils/callback.py`) enables observability and instrumentation of program execution:
```mermaid
graph LR
A[Module Forward] -->|on_module_start| B[Callback Handler]
B --> C[Execute]
C -->|on_module_end| B
```
The `CallbackHandler` base class defines hooks for:
| Hook | Trigger |
|------|---------|
| `on_module_start()` | Before a module's `forward()` executes |
| `on_module_end()` | After a module's `forward()` completes |
| `on_lm_start()` | Before an LM call |
| `on_lm_end()` | After an LM call |
Callbacks can be attached either globally or per-component:
```python
# Global callback
dspy.LM("gpt-3.5-turbo", callbacks=[LoggingCallback()])
# Local callback on specific component
lm(question="What is 2+2?", callbacks=[LoggingCallback()])
```
资料来源：[dspy/utils/callback.py:1-40]()
## Component Hierarchy
```mermaid
graph TD
BaseModule[BaseModule
dspy.primitives]
Module[Module
extends BaseModule]
Program[User Program
extends Module]
Predict[Predict
Signature-driven predictor]
ChainOfThought[ChainOfThought
extends Predict]
RLM[RLM
extends Module]
Example[Example
Data primitive]
Prediction[Prediction
Output primitive]
BaseModule --> Module
Module --> Program
Module --> Predict
Predict --> ChainOfThought
Module --> RLM
Example --> Program
Program --> Prediction
```
## Key Design Principles
1. **Separation of Concerns**: Data (`Example`, `Prediction`), structure (`Module`), and execution (`LM`) are cleanly separated
2. **Introspection**: The module system supports dynamic discovery of contained predictors
3. **Recursive Configuration**: Language model and other settings propagate through nested modules
4. **Serialization**: All data primitives support conversion to JSON-compatible formats
5. **Extensibility**: Custom modules can inherit from `Module` and use the same infrastructure
## Summary
DSPy's core architecture provides a composable framework where `Example` objects define inputs and labels, `Module` subclasses implement programs, `Predict` modules handle signature-driven LM interactions, and `Prediction` objects capture outputs. This architecture enables systematic optimization and evaluation of language model programs through a consistent, introspectable API.
---
## Signatures System
### 相关页面
相关主题：[Core Architecture](#core-architecture), [Prediction Modules](#predict-modules)
相关源码文件
以下源码文件用于生成本页说明：
- [dspy/signatures/__init__.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/signatures/__init__.py)
- [dspy/signatures/signature.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/signatures/signature.py)
- [dspy/signatures/field.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/signatures/field.py)
- [dspy/signatures/utils.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/signatures/utils.py)
# Signatures System
## Overview
The Signatures System is a core abstraction in DSPy that defines the structure of inputs and outputs for language model calls. A Signature describes what fields a module expects as input and what fields it will produce as output, effectively serving as a declarative contract between DSPy programs and language models.
Signatures enable DSPy to:
- Compile declarative LM calls into self-improving pipelines
- Separate input fields from output fields for proper data routing
- Provide rich metadata (descriptions) for each field that guides the LM's behavior
- Support dynamic field manipulation and signature transformation
资料来源：[dspy/signatures/signature.py:1-50]()
## Core Concepts
### InputField vs OutputField
Every field in a Signature is classified as either an `InputField` or an `OutputField`. This distinction is fundamental to DSPy's execution model:
| Field Type | Purpose | Behavior |
|------------|---------|----------|
| `InputField` | Data provided to the LM before generation | Passed in the prompt; LM reads but does not produce |
| `OutputField` | Data the LM should generate | Expected output; DSPy parses and validates the response |
```python
class MySignature(dspy.Signature):
question: str = dspy.InputField(desc="Input question")
answer: str = dspy.OutputField(desc="Generated answer")
```
资料来源：[dspy/signatures/field.py:1-30]()
### Field Descriptions
The `desc` parameter in InputField/OutputField provides natural language descriptions that are injected into prompts. Well-crafted descriptions significantly improve LM accuracy.
```python
class TranslationSignature(dspy.Signature):
english_text: str = dspy.InputField(desc="The text to translate, written in English")
french_text: str = dspy.OutputField(desc="The translated text in French")
```
## Signature Class
### Creating Signatures
Signatures can be created in multiple ways:
**Class-based definition:**
```python
class QASignature(dspy.Signature):
question: str = dspy.InputField()
answer: str = dspy.OutputField()
```
**String-based definition:**
```python
qa_sig = make_signature("question -> answer")
```
**Dictionary-based definition:**
```python
sig = make_signature({
"question": (str, dspy.InputField()),
"answer": (str, dspy.OutputField())
})
```
资料来源：[dspy/signatures/signature.py:200-280]()
### Signature Methods
The Signature class provides several class methods for creating modified copies:
| Method | Purpose |
|--------|---------|
| `with_instructions(instructions)` | Create a new Signature with updated instruction text |
| `with_updated_fields(name, type_=None, **kwargs)` | Update a field's metadata |
| `prepend(name, field, type_=None)` | Insert a field at the beginning |
| `append(name, field, type_=None)` | Insert a field at the end |
| `delete(name)` | Remove a field from the signature |
```python
# Update instructions
NewSig = MySig.with_instructions("Translate to French.")
# Add a new field
EnhancedSig = MySig.append("confidence", dspy.OutputField(desc="Translation confidence"))
# Remove a field
SimplifiedSig = MySig.delete("source_language")
```
资料来源：[dspy/signatures/signature.py:30-120]()
## Signature Structure and Fields
### Fields Dictionary
Internally, a Signature maintains a `fields` dictionary that maps field names to their corresponding `FieldInfo` objects:
```python
class Signature:
fields: dict[str, FieldInfo]
instructions: str
```
The fields are automatically categorized into inputs and outputs based on whether each field uses `InputField` or `OutputField`.
### Type Handling
Signatures support flexible type annotations:
```python
class CustomSig(dspy.Signature):
# Basic string type
text: str = dspy.InputField()
# With custom type
history: dspy.History = dspy.InputField()
# List of custom types
images: list[dspy.Image] = dspy.InputField()
```
When types are not explicitly provided, they default to `str` to maintain backward compatibility with existing programs.
资料来源：[dspy/signatures/utils.py:1-50]()
## Using Signatures with Examples
The `Example` class works in conjunction with Signatures to manage training data and evaluation:
### Marking Input Fields
```python
# Mark which fields are inputs vs labels
example = dspy.Example(
question="What is the capital of France?",
answer="Paris"
).with_inputs("question")
# Access inputs and labels separately
inputs = example.inputs() # Example({'question': '...'}) (input_keys={'question'})
labels = example.labels() # Example({'answer': '...'}) (input_keys={'question'})
```
### Converting Examples
```python
# Convert to dictionary for serialization
data = example.toDict()
# Copy with overrides
new_example = example.copy(answer="Lyon")
```
资料来源：[dspy/primitives/example.py:50-150]()
## Custom Types System
DSPy's Type system extends Signatures with custom data types. The base `Type` class requires implementations of the `format()` method.
### Built-in Custom Types
| Type | Purpose |
|------|---------|
| `dspy.Image` | Image inputs with URL or base64 encoding |
| `dspy.History` | Conversation history for multi-turn interactions |
### Image Type
```python
class Image(Type):
url: str
def format(self) -> list[dict[str, Any]]:
return [{"type": "image_url", "image_url": {"url": self.url}}]
```
```python
# Usage with signatures
class VQASignature(dspy.Signature):
image: dspy.Image = dspy.InputField(desc="Image to analyze")
question: str = dspy.InputField(desc="Question about the image")
answer: str = dspy.OutputField(desc="Answer to the question")
```
资料来源：[dspy/adapters/types/base_type.py:1-50]()
### History Type
```python
class History(Type):
messages: list[dict[str, Any]]
def format(self) -> list[dict[str, Any]]:
# Formats conversation history as a list of message dictionaries
pass
```
```python
# Usage for multi-turn conversations
class ChatSignature(dspy.Signature):
question: str = dspy.InputField()
history: dspy.History = dspy.InputField()
answer: str = dspy.OutputField()
```
资料来源：[dspy/adapters/types/history.py:1-60]()
## Architecture Diagram
```mermaid
graph TD
A[Signature Definition] --> B[Field Resolution]
B --> C{Field Type}
C -->|InputField| D[Input Fields Dict]
C -->|OutputField| E[Output Fields Dict]
F[make_signature] -->|String format| G[_parse_signature]
F -->|Dict format| H[Direct field assignment]
I[Example with Signature] --> J[with_inputs]
J --> K[Inputs]
J --> L[Labels]
M[Custom Types] --> N[Type.format]
N --> O[Image.format]
N --> P[History.format]
D --> Q[Predict Module]
E --> Q
Q --> R[LM Call]
```
## Field Modification Workflow
```mermaid
graph LR
A[Original Signature] --> B[with_updated_fields]
A --> C[prepend/append]
A --> D[delete]
B --> E[Updated field metadata]
C --> F[New field added]
D --> G[Field removed]
E --> H[Fresh Signature Instance]
F --> H
G --> H
```
## Advanced Usage
### Composing Multiple Signatures
Signatures can be dynamically combined using the insertion methods:
```python
class BaseSignature(dspy.Signature):
question: str = dspy.InputField()
answer: str = dspy.OutputField()
# Add context field
ExtendedSig = BaseSignature.prepend(
"context",
dspy.InputField(desc="Additional context")
)
# Add metadata output
FinalSig = ExtendedSig.append(
"confidence",
dspy.OutputField(desc="Confidence score")
)
```
### Custom Type Extraction
The Type system automatically extracts custom types from nested annotations:
```python
class MyType(dspy.Type):
@classmethod
def extract_custom_type_from_annotation(cls, annotation):
# Detects custom types in list[dict[str, MyType]]
pass
```
This enables DSPy to handle complex nested structures with custom types throughout the signature system.
资料来源：[dspy/adapters/types/base_type.py:40-80]()
## Best Practices
1. **Provide Clear Descriptions**: Always use descriptive `desc` parameters for fields to improve LM performance
2. **Explicit Input/Output Separation**: Use `.with_inputs()` to clearly mark which fields are inputs
3. **Leverage Type Annotations**: Use custom types like `Image` and `History` for structured data
4. **Immutability**: Remember that signature modification methods return new instances; originals are unchanged
## Related Components
| Component | File | Role |
|-----------|------|------|
| `Predict` | `dspy/predict/predict.py` | Consumes Signatures to execute LM calls |
| `Module` | `dspy/primitives/module.py` | Container for predictor modules |
| `Example` | `dspy/primitives/example.py` | Training/evaluation data with signature alignment |
| `Type` | `dspy/adapters/types/base_type.py` | Base class for custom types |
## Summary
The Signatures System is the foundational abstraction in DSPy that defines the interface between programs and language models. By separating inputs from outputs and providing rich metadata through field descriptions, Signatures enable DSPy's compilation and optimization capabilities. The system supports flexible creation methods, dynamic modification, and integration with custom types for complex applications.
---
## Module System
### 相关页面
相关主题：[Core Architecture](#core-architecture), [Prediction Modules](#predict-modules)
相关源码文件
以下源码文件用于生成本页说明：
- [dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
- [dspy/primitives/base_module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/base_module.py)
- [dspy/predict/predict.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/predict.py)
- [dspy/predict/parameter.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/parameter.py)
- [dspy/signatures/signature.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/signatures/signature.py)
# Module System
The DSPy Module System provides a declarative, composable framework for building language model programs. It serves as the foundational abstraction layer that enables automatic optimization of both prompts and model weights through DSPy's teleprompter system.
## Overview
DSPy's module system extends Python's native class mechanism to create reusable, optimizable building blocks for LLM pipelines. Unlike traditional Python modules, DSPy modules represent computational stages that can be automatically configured, optimized, and composed into larger programs.
```mermaid
graph TD
A[dspy.Module] --> B[dspy.Predict]
A --> C[dspy.ChainOfThought]
A --> D[dspy.MultiChainComparison]
A --> E[User-defined Module]
B --> F[Signature]
B --> G[Language Model]
E --> H[Other DSPy Modules]
```
资料来源：[dspy/primitives/module.py:1-50]()
## Core Components
### Module Base Class
The `dspy.Module` class serves as the foundation for all DSPy components. It extends Python's `nn.Module` to integrate seamlessly with neural network training paradigms while adding DSPy-specific functionality.
| Method | Purpose | Returns |
|--------|---------|---------|
| `forward()` | Execute the module's computation | `Prediction` or similar |
| `named_predictors()` | List all Predict submodules with names | `list[tuple[str, Predict]]` |
| `predictors()` | Return all Predict instances | `list[Predict]` |
| `set_lm(lm)` | Set language model for all predictors | `None` |
| `get_lm()` | Retrieve the configured language model | `LM` instance |
资料来源：[dspy/primitives/module.py:60-95]()
### Predictor Parameters
DSPy uses `Predict` and `Parameter` classes to define trainable components within modules. These parameters encapsulate the signature and configuration for LLM calls.
```python
class Parameter(dspy.BaseModule):
"""Trainable parameter that wraps a Predict module."""
def __init__(self, signature, **kwargs):
self.signature = signature
self.kwargs = kwargs
```
资料来源：[dspy/predict/parameter.py:1-20]()
## Module Hierarchy
```mermaid
graph TD
A[nn.Module] --> B[dspy.BaseModule]
B --> C[dspy.Module]
C --> D[dspy.Predict]
C --> E[User Module]
D --> F[ChainOfThought]
D --> G[Retry]
E --> H[Composite Programs]
F --> I[MultiChainComparison]
```
### BaseModule
`BaseModule` provides the essential interface that all DSPy components implement. It establishes the contract for modules that can be used within DSPy programs.
### Module
The `Module` class adds advanced functionality including:
- **Automatic predictor discovery**: Scans submodules to find all `Predict` instances
- **Language model management**: Centralized LM configuration across the module tree
- **Serialization support**: Ability to save and load compiled programs
资料来源：[dspy/primitives/module.py:40-80]()
## Predictor System
### Predict Class
`Predict` is the primary building block for LLM interactions. It binds a `Signature` to a language model call.
```python
class Predict(Module):
def __init__(self, signature, **config):
self.signature = dspy.Signature(signature)
self.config = config
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `signature` | `str` or `Signature` | Input/output field definitions |
| `lm` | `LM` | Language model to use (optional) |
| `temperature` | `float` | Sampling temperature (default: varies by LM) |
| `max_tokens` | `int` | Maximum tokens in response |
资料来源：[dspy/predict/predict.py:1-60]()
### Predictor Discovery
Modules can automatically discover their predictor submodules:
```python
class MyProgram(dspy.Module):
def __init__(self):
super().__init__()
self.qa = dspy.Predict("question -> answer")
self.summarize = dspy.Predict("text -> summary")
program = MyProgram()
for name, predictor in program.named_predictors():
print(f"{name}: {predictor.signature}")
# Output:
# qa: question -> answer
# summarize: text -> summary
```
资料来源：[dspy/primitives/module.py:50-65]()
## Language Model Integration
### Setting Language Models
Language models can be set at different levels of granularity:
```python
# Set LM for entire module tree
program.set_lm(dspy.LM("openai/gpt-4o-mini"))
# Set LM for specific predictor
program.qa.lm = dspy.LM("anthropic/claude-3")
# Retrieve configured LM
lm = program.get_lm()
```
资料来源：[dspy/primitives/module.py:80-95]()
## Signature System
Signatures define the schema for module inputs and outputs. They are central to the module system's type safety and documentation.
```python
class Signature:
@classmethod
def with_instructions(cls, instructions: str) -> type["Signature"]:
"""Create new Signature with custom instructions."""
return Signature(cls.fields, instructions)
@classmethod
def with_updated_fields(cls, name: str, **kwargs) -> type["Signature"]:
"""Update field metadata (descriptions, types)."""
fields_copy = deepcopy(cls.fields)
fields_copy[name].json_schema_extra.update(kwargs)
return Signature(fields_copy, cls.instructions)
```
资料来源：[dspy/signatures/signature.py:1-50]()
| Method | Purpose |
|--------|---------|
| `prepend()` | Add input field at the beginning |
| `append()` | Add output field at the end |
| `delete()` | Remove a field |
| `with_instructions()` | Create copy with new instructions |
| `with_updated_fields()` | Update field metadata |
## Creating Custom Modules
Custom modules extend `dspy.Module` and compose existing predictors:
```python
import dspy
class RAG(dspy.Module):
def __init__(self, num_passages=5):
super().__init__()
self.retrieve = dspy.Retrieve(k=num_passages)
self.generate_answer = dspy.ChainOfThought("context, question -> answer")
def forward(self, question):
context = self.retrieve(query=question).passages
return self.generate_answer(context=context, question=question)
```
## Workflow Diagram
```mermaid
graph LR
A[Define Module] --> B[Compose Predictors]
B --> C[Set Language Model]
C --> D[Compile with Teleprompter]
D --> E[Optimized Program]
E --> F[Execute on new inputs]
```
## Module Configuration Options
| Option | Predictor Parameter | Default | Effect |
|--------|---------------------|---------|--------|
| `temperature` | Per-call | LM default | Controls randomness |
| `max_tokens` | Per-call | LM default | Limits response length |
| `top_p` | Per-call | 1.0 | Nucleus sampling threshold |
| `cache` | Global | True | Enable response caching |
## Compilation and Optimization
Modules interface with DSPy's teleprompter system for automatic optimization:
```python
from dspy.teleprompt import BootstrapFewShot
optimizer = BootstrapFewShot(metric=my_metric)
compiled_program = optimizer.compile(
student=MyProgram(),
trainset=training_examples
)
```
The module system provides hooks for:
- **Prompt optimization**: Automatically improving instructions
- **Weight optimization**: Fine-tuning model weights via `BootstrapFinetune`
- **Demonstration selection**: Choosing optimal few-shot examples
资料来源：[dspy/primitives/module.py:1-30]()
## See Also
- [Signature System](../signatures/signature.md) - Input/output schema definitions
- [Predict Module](../predict/predict.md) - Core LLM interaction component
- [Teleprompters](../teleprompt/overview.md) - Optimization strategies
- [Evaluator](../evaluation/evaluator.md) - Metrics and evaluation
---
## Adapters
### 相关页面
相关主题：[Language Model Clients](#lm-clients)
相关源码文件
以下源码文件用于生成本页说明：
- [dspy/adapters/__init__.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/__init__.py)
- [dspy/adapters/base.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/base.py)
- [dspy/adapters/chat_adapter.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/chat_adapter.py)
- [dspy/adapters/json_adapter.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/json_adapter.py)
- [dspy/adapters/xml_adapter.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/xml_adapter.py)
- [dspy/adapters/two_step_adapter.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/two_step_adapter.py)
- [dspy/adapters/baml_adapter.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/baml_adapter.py)
- [dspy/adapters/types/base_type.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/types/base_type.py)
- [dspy/adapters/types/history.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/types/history.py)
- [dspy/adapters/types/image.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/adapters/types/image.py)
# Adapters
Adapters in DSPy are core components responsible for formatting and structuring messages sent to Language Models (LMs). They act as an intermediary layer between DSPy's internal data structures and the API formats expected by various LLM providers.
## Overview
When a DSPy module executes a signature (such as `dspy.Predict` or `dspy.ChainOfThought`), the adapter transforms the structured input/output fields into a format the LM can understand, and then parses the LM's response back into structured data.
```mermaid
graph LR
A[Signature Fields] --> B[Adapter]
B --> C[LM API Format]
C --> D[LM Response]
D --> B
B --> E[Structured Output]
```
**Key Responsibilities:**
| Responsibility | Description |
|----------------|-------------|
| Input Formatting | Convert DSPy input fields into prompt content |
| Output Parsing | Parse LM responses into structured output fields |
| Format Selection | Support various output formats (JSON, XML, Chat, etc.) |
| Type Handling | Process custom types like `Image`, `History`, etc. |
资料来源：[dspy/adapters/__init__.py:1-50]()
## Architecture
### Base Adapter
All adapters inherit from `dspy.adapters.base.BaseAdapter`, which defines the common interface:
```mermaid
classDiagram
class BaseAdapter {
+format(signature, demos, inputs) List[Message]
+parse(signature, completion) dict
+format_extractors(signature) str
}
class ChatAdapter {
+format(signature, demos, inputs)
+parse(signature, completion)
}
class JSONAdapter {
+format(signature, demos, inputs)
+parse(signature, completion)
}
class XMLAdapter {
+format(signature, demos, inputs)
+parse(signature, completion)
}
BaseAdapter <|-- ChatAdapter
BaseAdapter <|-- JSONAdapter
BaseAdapter <|-- XMLAdapter
```
**BaseAdapter Methods:**
| Method | Purpose |
|--------|---------|
| `format(signature, demos, inputs)` | Format inputs and demonstrations into messages for the LM |
| `parse(signature, completion)` | Parse LM completion text into structured output dictionary |
| `format_extractors(signature)` | Generate extractor prompt text for output fields |
资料来源：[dspy/adapters/base.py:1-100]()
### Adapter Selection
Adapters can be selected at different levels:
1. **Global Configuration**: Set via `dspy.configure(adapter=...)`
2. **Per-Module**: Pass `adapter` parameter to module constructors
3. **Default**: `ChatAdapter` is used when no adapter is specified
```python
# Global configuration
dspy.configure(adapter=dspy.JSONAdapter())
# Per-module configuration
predict = dspy.Predict("question -> answer", adapter=dspy.XMLAdapter())
```
## Built-in Adapters
### ChatAdapter
The default adapter that formats messages in OpenAI's chat format. It uses special delimiters to separate input fields, demonstrations, and output fields.
**Characteristics:**
| Feature | Value |
|---------|-------|
| Format | Chat messages array |
| Delimiter | `<>` / `<>` / `<>` |
| Best For | General purpose, GPT-4, Claude models |
**Message Structure:**
```mermaid
graph TD
A[System Message] --> B[Instructions]
B --> C[Input Fields]
C --> D[Demos Section]
D --> E[Output Fields Request]
E --> F[User Message]
```
资料来源：[dspy/adapters/chat_adapter.py:1-150]()
### JSONAdapter
Formats outputs as JSON, instructing the LM to respond with valid JSON that can be directly parsed.
**Characteristics:**
| Feature | Value |
|---------|-------|
| Format | JSON in response |
| Extraction | JSON parsing |
| Best For | Structured data extraction, function calling |
**Parsing Logic:**
```python
# The adapter looks for JSON blocks in the completion
json_match = re.search(r"```json\s*(.*?)\s*```", completion, re.DOTALL)
if json_match:
return json.loads(json_match.group(1))
```
资料来源：[dspy/adapters/json_adapter.py:1-100]()
### XMLAdapter
Uses XML-style tags to delimit fields, providing a structured format similar to HTML/XML.
**Characteristics:**
| Feature | Value |
|---------|-------|
| Format | XML-tagged response |
| Delimiter | ``, ``, etc. |
| Best For | Hierarchical or nested outputs |
**Example Output Format:**
```xml
The capital of France is Paris.
```
资料来源：[dspy/adapters/xml_adapter.py:1-100]()
### TwoStepAdapter
A specialized adapter that breaks the response into two steps:
1. **Thought Step**: The LM first provides reasoning or analysis
2. **Response Step**: The LM provides the final structured output
This adapter is particularly useful with `dspy.ChainOfThought` modules.
资料来源：[dspy/adapters/two_step_adapter.py:1-100]()
### BamlAdapter
Adapter specifically designed for BAML (Business Application Markup Language) output formatting, used with BAML-compiled signatures.
资料来源：[dspy/adapters/baml_adapter.py:1-50]()
## Custom Types
DSPy adapters support custom types that can be used in signatures:
### Image Type
The `Image` type allows passing images to multimodal models:
```python
import dspy
from dspy.adapters.types import Image
class VisionSignature(dspy.Signature):
image: Image = dspy.InputField()
description: str = dspy.OutputField()
predict = dspy.Predict(VisionSignature)
result = predict(image=Image(url="https://example.com/image.jpg"))
```
**Image Formats Supported:**
| Format | Support |
|--------|---------|
| URL string | ✅ Direct URL |
| Base64 | ✅ Embedded data URI |
| File path | ✅ Local file path |
| PIL Image | ✅ In-memory image |
| Bytes | ✅ Raw bytes |
资料来源：[dspy/adapters/types/image.py:1-80]()
### History Type
The `History` type allows passing conversation history:
```python
import dspy
from dspy.adapters.types import History
class ConversationSignature(dspy.Signature):
history: History = dspy.InputField()
question: str = dspy.InputField()
answer: str = dspy.OutputField()
history = History(messages=[
{"question": "What is 2+2?", "answer": "4"},
{"question": "What is 3+3?", "answer": "6"},
])
predict = dspy.Predict(ConversationSignature)
result = predict(history=history, question="What is 5+5?")
```
资料来源：[dspy/adapters/types/history.py:1-100]()
### Custom Type Identifiers
When custom types are used, adapters use special identifiers:
| Identifier | Purpose |
|------------|---------|
| `<>` | Marks start of custom type content |
| `<>` | Marks end of custom type content |
These identifiers help adapters extract and process custom type content from LM responses.
资料来源：[dspy/adapters/types/base_type.py:1-50]()
## Workflow
```mermaid
sequenceDiagram
participant User
participant Module
participant Adapter
participant LM
participant Parser
User->>Module: Forward pass with inputs
Module->>Adapter: format(signature, demos, inputs)
Adapter->>Adapter: Structure messages
Adapter->>LM: Send formatted messages
LM-->>Adapter: Return completion
Adapter->>Parser: parse(signature, completion)
Parser->>Parser: Extract structured fields
Parser-->>Module: Return dict output
Module-->>User: Return structured output
```
## Configuration Options
### Adapter Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `caching` | bool | True | Enable response caching |
| `batch_size` | int | 200 | Batch size for embedding operations |
| `default_kwargs` | dict | {} | Default arguments passed to LM |
### Setting Adapters
```python
import dspy
# Method 1: Global configuration
dspy.configure(adapter=dspy.JSONAdapter())
# Method 2: Per-module
predict = dspy.Predict(
"question -> answer",
adapter=dspy.XMLAdapter()
)
# Method 3: At initialization
dspy.settings.adapter = dspy.ChatAdapter()
```
## Best Practices
1. **Use JSONAdapter** when you need strict structured output parsing
2. **Use ChatAdapter** for general-purpose applications (default)
3. **Use XMLAdapter** for nested or hierarchical data structures
4. **Use TwoStepAdapter** with `ChainOfThought` for reasoning-intensive tasks
5. **Use custom types** (`Image`, `History`) for multimodal or conversational applications
## Extending Adapters
To create a custom adapter, inherit from `BaseAdapter`:
```python
from dspy.adapters import BaseAdapter
class MyCustomAdapter(BaseAdapter):
def format(self, signature, demos, inputs):
# Custom formatting logic
messages = []
# ... format messages ...
return messages
def parse(self, signature, completion):
# Custom parsing logic
return {"output_field": parsed_value}
```
## Summary
Adapters are a fundamental part of DSPy's architecture, providing a flexible abstraction layer between DSPy's declarative signatures and the various API formats expected by different LMs. By supporting multiple built-in adapters and allowing custom extensions, DSPy can work seamlessly with any language model while maintaining a consistent programming interface.
| Adapter | Use Case |
|---------|----------|
| `ChatAdapter` | Default, general purpose |
| `JSONAdapter` | Structured JSON output |
| `XMLAdapter` | XML-tagged output |
| `TwoStepAdapter` | Reasoning + response |
| `BamlAdapter` | BAML format |
---
## Language Model Clients
### 相关页面
相关主题：[Adapters](#adapters)
相关源码文件
以下源码文件用于生成本页说明：
- [dspy/clients/__init__.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/__init__.py)
- [dspy/clients/lm.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/lm.py)
- [dspy/clients/base_lm.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/base_lm.py)
- [dspy/clients/openai.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/openai.py)
- [dspy/clients/_litellm.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/_litellm.py)
- [dspy/clients/databricks.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/databricks.py)
- [dspy/clients/lm_local.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/lm_local.py)
- [dspy/clients/cache.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/clients/cache.py)
# Language Model Clients
## Overview
The Language Model (LM) client system in DSPy provides a unified interface for interacting with various LLM providers. This abstraction layer enables developers to swap between different LLM backends (OpenAI, Anthropic, Azure, local models, etc.) without modifying application code.
## Architecture
The LM client architecture follows a layered design pattern with a base class defining the common interface and provider-specific implementations extending it.
```mermaid
graph TD
A[Application Code] --> B[dspy.LM Interface]
B --> C[OpenAI Client]
B --> D[LiteLLM Client]
B --> E[Databricks Client]
B --> F[Local LM Client]
C --> G[OpenAI API]
D --> H[40+ LLM Providers]
E --> I[Databricks Endpoint]
F --> J[Ollama / vLLM]
```
## Core Components
### BaseLM Abstract Class
The `BaseLM` class defines the abstract interface that all LM clients must implement. This ensures consistency across different providers.
| Method | Purpose | Return Type |
|--------|---------|-------------|
| `__call__` | Execute a completion request | `dict` |
| `get_reference` | Retrieve cached responses | `dict \| None` |
| `inspect_history` | View conversation history | `list[dict]` |
| `drop_cache` | Clear the response cache | `None` |
资料来源：[dspy/clients/base_lm.py]()
### LM Factory Class
The main `LM` class serves as a factory that instantiates the appropriate client based on the model identifier format.
Supported model formats include:
- `provider/model-name` (e.g., `openai/gpt-4`, `anthropic/claude-3`)
- `provider/model-name@timestamp` (e.g., `openai/gpt-4o-mini-2024-07-18`)
- `provider/model-name:variant` (e.g., `openai/gpt-4-turbo:n-1106`)
```python
# Example instantiation patterns
lm = dspy.LM("openai/gpt-4o-mini")
lm = dspy.LM("anthropic/claude-3-opus-20240229")
lm = dspy.LM("azure/gpt-4o", api_base="https://...", api_key="...")
```
资料来源：[dspy/clients/lm.py:1-100]()
## LM Client Implementations
### OpenAI Client
The OpenAI client provides direct integration with OpenAI's API endpoints.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `model` | `str` | Required | Model name (e.g., `gpt-4o-mini`) |
| `api_key` | `str` | Environment | API key from `OPENAI_API_KEY` |
| `api_base` | `str` | Official API | Custom endpoint URL |
| `temperature` | `float` | `0.0` | Sampling temperature |
| `max_tokens` | `int` | `1024` | Maximum completion tokens |
| `timeout` | `int \| float` | `120` | Request timeout in seconds |
资料来源：[dspy/clients/openai.py]()
### LiteLLM Client
The LiteLLM client wraps the `litellm` library, providing access to over 40 LLM providers through a unified interface.
```python
# Using LiteLLM-backed LM
lm = dspy.LM("anthropic/claude-3-sonnet-20240229",
api_key=os.getenv("ANTHROPIC_API_KEY"))
```
Supported providers include:
- Anthropic
- Azure OpenAI
- AWS Bedrock
- Google Vertex AI
- Cohere
- Mistral
- Together AI
资料来源：[dspy/clients/_litellm.py]()
### Databricks Client
The Databricks client integrates with Databricks Model Serving endpoints for enterprise deployments.
```python
from dspy.clients.databricks import Databricks
lm = Databricks(
model="databricks-meta-llama-3-70b-instruct",
Databricks_host="https://your-workspace.cloud.databricks.com",
Databricks_token="your-token",
)
```
| Parameter | Description |
|-----------|-------------|
| `model` | Databricks model endpoint name |
| `Databricks_host` | Workspace URL |
| `Databricks_token` | Authentication token |
资料来源：[dspy/clients/databricks.py]()
### Local LM Client
The Local LM client supports self-hosted models through Ollama or vLLM.
```python
from dspy.clients.lm_local import LocalLM
# Using Ollama
lm = LocalLM(model="llama3", base_url="http://localhost:11434")
# Using vLLM
lm = LocalLM(model="mistralai/Mistral-7B-Instruct-v0.2", base_url="http://localhost:8000")
```
资料来源：[dspy/clients/lm_local.py]()
## Caching System
DSPy implements a response caching mechanism to reduce API costs and improve latency for repeated requests.
```mermaid
graph LR
A[Request] --> B{Cache Hit?}
B -->|Yes| C[Return Cached Response]
B -->|No| D[Execute LM Call]
D --> E[Store in Cache]
E --> F[Return Response]
```
### Cache Configuration
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `cache` | `Cache` | `None` | Cache instance |
| `cache_turns` | `bool` | `False` | Include conversation turns in cache key |
The cache uses a hash-based key generation strategy:
1. Serialize the input prompt
2. Serialize adapter inputs and configuration
3. Combine and hash to create cache key
资料来源：[dspy/clients/cache.py]()
## Callback System
Callbacks enable monitoring and logging of LM interactions throughout the application.
```mermaid
graph TD
A[LM Call] --> B[Callback Manager]
B --> C[on_module_start]
B --> D[on_module_end]
B --> E[on_lm_start]
B --> F[on_lm_end]
```
### Built-in Callbacks
| Callback | Trigger | Purpose |
|----------|---------|---------|
| `LoggingCallback` | Every LM call | Log inputs/outputs to console |
| Custom `Handler` | Per event type | User-defined monitoring logic |
```python
class LoggingCallback(Handler):
def on_lm_start(self, call_id, instance, inputs):
print(f"LM is called with inputs: {inputs}")
def on_lm_end(self, call_id, instance, outputs):
print(f"LM is finished with outputs: {outputs}")
```
资料来源：[dspy/utils/callback.py]()
## Configuration Options
### Global Configuration
Configure LM settings globally using `dspy.configure()`:
```python
import dspy
dspy.configure(
lm=dspy.LM("openai/gpt-4o-mini"),
rm=dspy.Retrieve(k=3),
max_tokens=512,
temperature=0.1,
)
```
### Per-Instance Configuration
Override settings at the component level:
```python
cot = dspy.ChainOfThought(
"question -> answer",
temperature=0.5,
max_tokens=256
)
```
### Configuration Precedence
| Level | Override Priority | Example |
|-------|-------------------|---------|
| Component | Highest | `dspy.Predict(..., temperature=0.8)` |
| Global | Middle | `dspy.configure(temperature=0.5)` |
| Default | Lowest | `dspy.LM("...")` default value |
## Usage Patterns
### Basic Usage
```python
import dspy
# Initialize LM
lm = dspy.LM("openai/gpt-4o-mini")
# Direct call
result = lm("What is the capital of France?")
print(result)
```
### With Modules
```python
import dspy
lm = dspy.LM("openai/gpt-4o-mini")
# Set LM for a module
program = dspy.Predict("question -> answer")
program.set_lm(lm)
# Execute
result = program(question="What is 2+2?")
```
### Batch Processing
```python
import dspy
lm = dspy.LM("openai/gpt-4o-mini", max_tokens=100)
# Multiple calls tracked in history
for q in questions:
lm(q)
# Inspect all calls
for item in lm.inspect_history():
print(item)
```
## Error Handling
The LM client system handles various error conditions:
| Error Type | Cause | Handling Strategy |
|------------|-------|-------------------|
| `AuthenticationError` | Invalid API key | Check environment variables |
| `RateLimitError` | API quota exceeded | Implement backoff/retry |
| `APIResponseValidationError` | Malformed response | Automatic retry with backoff |
| `ContextWindowExceededError` | Input too long | Reduce prompt size |
## Best Practices
1. **Use environment variables** for API keys to avoid hardcoding credentials
2. **Enable caching** for development and testing to reduce API costs
3. **Set appropriate `max_tokens`** to prevent overly long responses
4. **Use callbacks** for production monitoring and debugging
5. **Configure timeouts** appropriately for your use case (default: 120s)
## See Also
- [Signature System](../signatures/signature.md) - How DSPy defines input/output schemas
- [Modules](../primitives/module.md) - Using LMs within DSPy modules
- [Teleprompters](../teleprompt/teleprompt.md) - Optimizing prompts with LMs
- [Retrievers](../retrievers/retriever.md) - Combining LMs with retrieval systems
---
## Prediction Modules
### 相关页面
相关主题：[Module System](#modules), [Agent Modules](#agent-modules)
相关源码文件
以下源码文件用于生成本页说明：
- [dspy/predict/__init__.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/__init__.py)
- [dspy/predict/predict.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/predict.py)
- [dspy/predict/chain_of_thought.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/chain_of_thought.py)
- [dspy/predict/multi_chain_comparison.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/multi_chain_comparison.py)
- [dspy/predict/best_of_n.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/best_of_n.py)
- [dspy/predict/parallel.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/parallel.py)
- [dspy/predict/refine.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/refine.py)
- [dspy/predict/aggregation.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/aggregation.py)
- [dspy/predict/retry.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/retry.py)
- [dspy/predict/knn.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/knn.py)
# Prediction Modules
## Overview
Prediction Modules are the core building blocks in DSPy for executing language model calls. They encapsulate the logic for invoking language models, handling inputs/outputs defined by Signatures, and providing various reasoning and optimization strategies. All predictors inherit from the base `Predict` class and can be composed within `dspy.Module` objects to build complex AI pipelines.
**Key responsibilities:**
- Execute language model calls with specified inputs
- Parse and validate model outputs according to Signature definitions
- Support multiple reasoning strategies (chain-of-thought, multi-chain comparison, etc.)
- Integrate with DSPy's teleprompters for automatic prompt optimization
- Track execution history for debugging and introspection
资料来源：[dspy/predict/predict.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/predict.py)
---
## Base Predict Class
The `Predict` class serves as the foundation for all prediction modules. It wraps a Signature that defines input and output fields.
### Basic Usage
```python
import dspy
# Simple question answering
qa = dspy.Predict("question -> answer")
qa(question="What is the capital of France?", lm=dspy.LM("openai/gpt-4o-mini"))
```
### Signature Definition
Signatures define the schema for inputs and outputs:
```python
classify = dspy.Predict(
"sentence -> sentiment: str, confidence: float"
)
```
资料来源：[dspy/predict/predict.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/predict.py)
---
## Specialized Predictor Types
### Chain of Thought (CoT)
`ChainOfThought` generates reasoning steps before producing the final answer. This technique improves accuracy on complex reasoning tasks.
```python
cot = dspy.ChainOfThought("question -> answer")
result = cot(question="If I have 5 apples and eat 2, how many do I have left?")
# Includes reasoning trace in addition to answer
```
资料来源：[dspy/predict/chain_of_thought.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/chain_of_thought.py)
### Multi Chain Comparison (MCC)
`MultiChainComparison` generates multiple reasoning chains and compares them to produce a more robust answer.
```python
mcc = dspy.MultiChainComparison("question -> answer", n=3)
result = mcc(question="Explain why the sky is blue")
```
资料来源：[dspy/predict/multi_chain_comparison.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/multi_chain_comparison.py)
### Parallel Predictor
`Parallel` executes multiple predictors simultaneously and returns all results.
```python
parallel = dspy.Parallel(
dspy.Predict("question -> short_answer"),
dspy.Predict("question -> detailed_answer")
)
results = parallel(question="What is Python?")
```
资料来源：[dspy/predict/parallel.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/parallel.py)
### Best of N
`BestOfN` generates N candidates and selects the best one based on a provided metric.
```python
best_of = dspy.BestOfN("question -> answer", n=5, metric=my_metric)
result = best_of(question="What is 2+2?")
```
资料来源：[dspy/predict/best_of_n.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/best_of_n.py)
### Retry
`Retry` automatically retries failed or low-quality predictions with modified prompts.
```python
retry = dspy.Retry("question -> answer", max_retries=3)
result = retry(question="Explain quantum entanglement")
```
资料来源：[dspy/predict/retry.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/retry.py)
### Refine
`Refine` iteratively improves predictions through successive refinement steps.
```python
refine = dspy.Refine("question -> answer", max_iters=5)
result = refine(question="Write a haiku about coding")
```
资料来源：[dspy/predict/refine.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/refine.py)
### Aggregation
`Aggregation` combines outputs from multiple predictors using various strategies (voting, majority, etc.).
```python
agg = dspy.Aggregation("observation -> conclusion", strategy="majority_vote")
result = agg(observation="Multiple sensors detected movement")
```
资料来源：[dspy/predict/aggregation.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/aggregation.py)
### KNN Predictor
`KNN` uses k-nearest neighbors approach for predictions based on similar training examples.
```python
knn = dspy.KNN("input -> output", k=5)
knn.load_examples(trainset)
result = knn(input="similar text to training data")
```
资料来源：[dspy/predict/knn.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/knn.py)
---
## Integration with Modules
Predictors are typically used within `dspy.Module` subclasses for building complete programs.
### Declaring Predictors in Modules
```python
import dspy
class RAGProgram(dspy.Module):
def __init__(self):
super().__init__()
self.retrieve = dspy.Predict("query -> context")
self.answer = dspy.ChainOfThought("context, question -> answer")
def forward(self, question):
context = self.retrieve(query=question)
return self.answer(context=context.context, question=question)
```
资料来源：[dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
### Managing Predictors
```python
program = RAGProgram()
# List all predictors
for name, predictor in program.named_predictors():
print(f"{name}: {predictor}")
# Get all predictor instances
all_predictors = program.predictors()
```
资料来源：[dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
---
## Language Model Configuration
### Setting LM for All Predictors
```python
lm = dspy.LM("openai/gpt-4o-mini")
program = RAGProgram()
program.set_lm(lm)
```
### Getting LM from Module
```python
lm = program.get_lm() # Returns LM if all predictors use the same one
```
资料来源：[dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
---
## Batch Processing
Predictors support batch execution with configurable parallelism and error handling:
```python
examples = [
dspy.Example(question="What is 1+1?").with_inputs("question"),
dspy.Example(question="What is 2+2?").with_inputs("question"),
]
results = program.batch(
examples=examples,
num_threads=4,
max_errors=2,
return_failed_examples=True,
)
```
资料来源：[dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
---
## History Inspection
View past executions for debugging:
```python
# Inspect last prediction
program.inspect_history(n=1)
# Inspect last 5 predictions with output to file
program.inspect_history(n=5, file=open("history.txt", "w"))
```
资料来源：[dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
---
## Transformative Operations
Apply transformations to all predictors in a module:
```python
# Wrap all predictors with Retry
program.map_named_predictors(lambda p: dspy.Retry(p))
```
资料来源：[dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
---
## Architecture Diagram
```mermaid
graph TD
A[dspy.Module] --> B[Predict]
A --> C[ChainOfThought]
A --> D[MultiChainComparison]
A --> E[Parallel]
A --> F[Retry]
A --> G[Refine]
A --> H[BestOfN]
A --> I[Aggregation]
A --> J[KNN]
B --> K[Signature Definition]
B --> L[LM Invocation]
B --> M[Output Parsing]
N[Example Data] --> O[Batch Processing]
O --> B
O --> C
O --> D
P[Teleprompters] -.-> Q[Optimize Predictors]
Q --> B
Q --> C
```
---
## Complete Example
```python
import dspy
# Configure language model
lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)
# Define a multi-step program
class MedicalQAProgram(dspy.Module):
def __init__(self):
super().__init__()
self.classify = dspy.Predict("question -> category: str")
self.answer = dspy.ChainOfThought("category, question -> answer")
self.refine = dspy.Retry("category, question, answer -> refined_answer")
def forward(self, question):
category = self.classify(question=question)
answer = self.answer(category=category.category, question=question)
refined = self.refine(
category=category.category,
question=question,
answer=answer.answer
)
return refined
# Create and use program
program = MedicalQAProgram()
result = program(question="What are the symptoms of diabetes?")
print(result.refined_answer)
```
---
## Summary Table
| Predictor Type | Purpose | Key Parameter |
|----------------|---------|----------------|
| `Predict` | Base predictor for simple LM calls | `signature` |
| `ChainOfThought` | Generate reasoning traces | `signature`, `_reasoning` |
| `MultiChainComparison` | Compare multiple reasoning chains | `signature`, `n` |
| `Parallel` | Execute multiple predictors simultaneously | `*predictors` |
| `Retry` | Retry failed predictions | `max_retries`, `threshold` |
| `Refine` | Iteratively improve predictions | `max_iters` |
| `BestOfN` | Select best from N candidates | `n`, `metric` |
| `Aggregation` | Combine outputs via voting | `strategy` |
| `KNN` | K-nearest neighbors prediction | `k`, examples |
---
## See Also
- [Signature System](../core/signatures.md) - Input/output field definitions
- [Teleprompters](../teleprompt/overview.md) - Automatic prompt optimization
- [Module System](../primitives/module.md) - Composing predictors into programs
---
## Agent Modules
### 相关页面
相关主题：[Prediction Modules](#predict-modules)
Related Source Files
The following source files were used to generate this page:
- [dspy/predict/react.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/react.py)
- [dspy/predict/rlm.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/predict/rlm.py)
- [dspy/primitives/code_interpreter.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/code_interpreter.py)
- [dspy/primitives/python_interpreter.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/python_interpreter.py)
- [dspy/primitives/module.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/primitives/module.py)
- [dspy/propose/grounded_proposer.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/propose/grounded_proposer.py)
# Agent Modules
## Overview
Agent Modules in DSPy are specialized modules that enable language models to interact with external tools, execute code, and perform multi-step reasoning tasks. Unlike standard Predict modules that generate direct outputs, Agent Modules implement agentic behaviors where the LM can plan, take actions (such as calling tools or executing code), observe results, and iteratively refine their approach until reaching a final answer.
DSPy provides several agent implementations that share a common architectural pattern: they use a signature to define input/output fields, maintain a trajectory of their reasoning and actions, and leverage code interpreters or tool execution systems to perform computations that the language model cannot do directly.
资料来源：[dspy/primitives/module.py:1-50]()
## Architecture
### Core Components
Agent Modules in DSPy are built on a layered architecture:
```mermaid
graph TD
A[Agent Module
e.g., ReAct, Program of Thought] --> B[Signature
Input/Output Field Definitions]
A --> C[Tool Registry
Available Actions]
A --> D[History/Trajectory
Reasoning & Actions]
B --> E[Code Interpreter
Execution Backend]
C --> F[Tool Execution
Function Calls]
D --> G[Observation Processing
Feedback Loop]
E --> H[Python Interpreter
Sandboxed Execution]
```
### Agent Base Pattern
All DSPy agent implementations follow a similar control flow:
1. **Initialization**: Set up signature, tools, and configuration parameters
2. **Loop Execution**: Iterate until max iterations or final output received
3. **Thought Generation**: LM produces reasoning and next action
4. **Action Execution**: Tools or code interpreters execute the proposed action
5. **Observation Processing**: Results are appended to trajectory
6. **Termination**: Return final prediction with full trajectory
资料来源：[dspy/predict/react.py:1-80]()
## ReAct Agent
The ReAct agent implements the Reasoning + Acting pattern, combining deliberate reasoning with tool usage. It allows language models to use external tools to gather information and complete tasks.
### Signature Configuration
```python
class ReAct(dspy.Module):
def __init__(
self,
signature,
max_iters: int = 10,
tools: list[Tool | Callable] = None,
):
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `signature` | `str \| Signature` | Required | Defines input/output fields for the task |
| `max_iters` | `int` | `10` | Maximum number of reasoning iterations |
| `tools` | `list[Tool \| Callable]` | `None` | List of tools available to the agent |
资料来源：[dspy/predict/react.py:50-90]()
### Tool Integration
The ReAct agent automatically generates instructions that inform the LM about available tools:
```python
inputs = ", ".join([f"`{k}`" for k in signature.input_fields.keys()])
outputs = ", ".join([f"`{k}`" for k in signature.output_fields.keys()])
instr = [
f"You are an Agent. In each episode, you will be given the fields {inputs} as input.",
f"Your goal is to use one or more of the supplied tools to collect any necessary information for producing {outputs}.",
]
```
Tools are converted to a `Tool` registry and made available by name for the agent to call.
资料来源：[dspy/predict/react.py:70-85]()
### Usage Example
```python
def get_weather(city: str) -> str:
return f"The weather in {city} is sunny."
react = dspy.ReAct(signature="question -> answer", tools=[get_weather])
pred = react(question="What is the weather in Tokyo?")
```
## Code Interpreter Agents
DSPy provides agents that can execute Python code to perform computations. These agents use a sandboxed Python interpreter to run code safely.
### Python Interpreter
The `PythonInterpreter` class provides the execution backend for code-based agents:
| Feature | Description |
|---------|-------------|
| **Sandboxed Execution** | Runs code in an isolated environment |
| **Variable Extraction** | Extracts variables from execution context |
| **Error Handling** | Catches and reports execution errors |
| **REPL Support** | Interactive read-eval-print loop style execution |
The interpreter extracts variables after each execution, making them available for subsequent code blocks or tool calls.
资料来源：[dspy/primitives/python_interpreter.py:1-60]()
### Code Interpreter Primitive
The `CodeInterpreter` class wraps the Python interpreter with additional utilities:
```python
class CodeInterpreter:
def __init__(self, max_output_chars: int = 2000):
self.max_output_chars = max_output_chars
def execute(self, code: str, variables: dict) -> Any:
# Execute code and return result
```
| Method | Description |
|--------|-------------|
| `execute(code, variables)` | Execute code string with provided variable context |
| `extract_variables(result)` | Extract Python objects from execution result |
资料来源：[dspy/primitives/code_interpreter.py:1-50]()
## Reflexion Language Model (RLM) Agent
The RLM agent implements a Reflexion-style approach where the agent maintains a history of reasoning, code execution, and observations to iteratively improve its output.
### Execution Flow
```mermaid
graph TD
A[Start with Input] --> B[Generate Reasoning]
B --> C[Generate Code]
C --> D[Execute Code in Interpreter]
D --> E{Error?}
E -->|Yes| F[Record Error in History]
F --> G[Generate Fix Reasoning]
G --> C
E -->|No| H{Is Final Output?}
H -->|No| B
H -->|Yes| I[Return Prediction with Trajectory]
```
### Trajectory Tracking
The RLM agent maintains a `REPLHistory` that tracks all iterations:
```python
return Prediction(
**parsed_outputs,
trajectory=[e.model_dump() for e in final_history],
final_reasoning=pred.reasoning,
)
```
Each history entry contains:
- `reasoning`: The agent's thought process
- `code`: The code that was executed
- `output`: The result or error message
资料来源：[dspy/predict/rlm.py:100-130]()
### Result Processing
The agent processes final outputs by parsing structured results:
```python
def _process_final_output(self, result: FinalOutput, output_field_names: list[str]):
parsed_outputs, error = self._process_final_output(result, output_field_names)
if error:
return history.append(reasoning=pred.reasoning, code=code, output=error)
```
## Program of Thought
The Program of Thought agent combines natural language reasoning with programmatic code execution, allowing the agent to offload complex calculations to executed code while maintaining reasoning chains.
### Architecture
```mermaid
graph LR
A[Input Question] --> B[Reasoning Module]
B --> C[Code Generation]
C --> D[Python Interpreter]
D --> E[Output Extraction]
E --> F{More Steps Needed?}
F -->|Yes| B
F -->|No| G[Final Answer]
```
## Tool Definition
DSPy uses a `Tool` class to wrap functions and make them available to agents:
```python
tool = Tool(
name="function_name",
func=my_function,
desc="Description for LLM"
)
```
Tools can be:
- Plain Python functions
- Decorated with the `@Tool` decorator
- Already instantiated `Tool` objects
## Configuration Parameters
### Common Agent Parameters
| Parameter | Type | Default | Agent Types |
|-----------|------|---------|-------------|
| `max_iters` | `int` | `10` | ReAct, RLM |
| `max_output_chars` | `int` | `2000` | RLM, Code-based |
| `temperature` | `float` | `0.0` | All agents |
| `verbose` | `bool` | `False` | All agents |
### History and Trajectory
Agents maintain execution history which can be inspected:
```python
agent = dspy.ReAct(signature="question -> answer", tools=[my_tool])
result = agent(question="What is 2+2?")
# Access trajectory
for step in result.trajectory:
print(f"Thought: {step['reasoning']}")
print(f"Action: {step['code']}")
print(f"Observation: {step['output']}")
```
## Integration with DSPy Module System
All agent modules inherit from `dspy.Module`, giving them access to:
- `named_predictors()`: List all Predict instances
- `set_lm(lm)`: Set language model for all predictors
- `get_lm()`: Retrieve the configured language model
- `inspect_history(n)`: Display recent LM call history
```python
class MyAgent(dspy.Module):
def __init__(self):
super().__init__()
self.predictor = dspy.ReAct("question -> answer", tools=[...])
def forward(self, question):
return self.predictor(question=question)
```
资料来源：[dspy/primitives/module.py:50-120]()
## Best Practices
### Tool Design
1. **Clear Function Names**: Use descriptive names that indicate the tool's purpose
2. **Type Annotations**: Add type hints for better LLM understanding
3. **Docstrings**: Provide clear descriptions of what the tool does
4. **Return Values**: Return string or serializable types for consistency
### Agent Configuration
1. **Set Appropriate `max_iters`**: Too few iterations may prevent task completion; too many wastes resources
2. **Use Temperature Control**: Lower temperatures (0.0-0.3) for deterministic tasks
3. **Inspect Trajectories**: Use `inspect_history()` for debugging agent behavior
### Error Handling
Agents should be configured with error handling for:
- Code execution failures
- Tool invocation errors
- Maximum iteration limits reached
- Invalid output parsing
---
## Optimizers (Teleprompt)
### 相关页面
相关主题：[Signatures System](#signatures)
相关源码文件
以下源码文件用于生成本页说明：
- [dspy/teleprompt/__init__.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/__init__.py)
- [dspy/teleprompt/bootstrap.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/bootstrap.py)
- [dspy/teleprompt/mipro_optimizer_v2.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/mipro_optimizer_v2.py)
- [dspy/teleprompt/copro_optimizer.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/copro_optimizer.py)
- [dspy/teleprompt/bettertogether.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/bettertogether.py)
- [dspy/teleprompt/ensemble.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/ensemble.py)
- [dspy/teleprompt/random_search.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/random_search.py)
- [dspy/teleprompt/grpo.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/grpo.py)
- [dspy/teleprompt/gepa/gepa.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/gepa/gepa.py)
- [dspy/teleprompt/bootstrap_finetune.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/bootstrap_finetune.py)
- [dspy/teleprompt/bootstrap_trace.py](https://github.com/stanfordnlp/dspy/blob/main/dspy/teleprompt/bootstrap_trace.py)
# Optimizers (Teleprompt)
## Overview
In DSPy, **Optimizers** (also referred to as **Teleprompters**) are compilation strategies that automatically optimize the prompts and/or weights of your LM programs. They take a raw program with a signature and training data, then search for improved instructions and/or demonstrations to include in the program's prompts.
The teleprompter system enables declarative, data-driven optimization of LLM pipelines without manual prompt engineering. Instead of crafting prompts by hand, you define:
1. Your program structure (modules, signatures)
2. A metric function to evaluate quality
3. A training set of examples
The optimizer then compiles your program by finding optimal combinations of instructions, demonstrations, and (optionally) fine-tuned weights.
## Architecture
The optimizer system follows a hierarchical architecture with a base `Teleprompter` abstract class and specialized subclasses for different optimization strategies:
```mermaid
graph TD
A[Teleprompter Base] --> B[Prompt Optimizers]
A --> C[Weight Optimizers]
A --> D[Meta-Optimizers]
B --> B1[BootstrapFewShot]
B --> B2[MIPROv2]
B --> B3[COPRO]
B --> B4[GEPA]
B --> B5[GRPO]
B --> B6[BootstrapFewShotWithRandomSearch]
C --> C1[BootstrapFinetune]
D --> D1[BetterTogether]
A --> E[Ensemble]
E --> E1[Ensemble]
```
## Base Class: Teleprompter
All optimizers inherit from the abstract `Teleprompter` class defined in `dspy/teleprompt/teleprompt.py`. The base interface requires implementing a `compile()` method.
### Compile Interface
```python
def compile(self, student: Module, *, trainset: list[Example], ...) -> Module:
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `student` | `Module` | The program to optimize |
| `trainset` | `list[Example]` | Training examples for optimization |
| `valset` | `list[Example]` | Optional validation set for selecting best program |
| `teacher` | `Module \| list[Module]` | Optional teacher program for bootstrapping |
| `strategy` | `str` | Execution strategy for meta-optimizers |
## Prompt Optimizers
Prompt optimizers focus on improving the instructions and demonstrations in your program's prompts without modifying model weights.
### BootstrapFewShot
`BootstrapFewShot` is the foundational prompt optimizer that composes demonstrations (examples) into a predictor's prompt. These demos come from two sources:
1. **Labeled examples** from the training set
2. **Bootstrapped demos** generated by running the program with the LM
**Key Features:**
- Each bootstrap round copies the LM with a new `rollout_id` at `temperature=1.0` to bypass caches and gather diverse traces
- Supports multi-round bootstrapping for complex multi-step programs
资料来源：[dspy/teleprompt/bootstrap.py:20-45]()
```python
teleprompter = BootstrapFewShot(
metric=your_metric,
metric_threshold=0.5, # Minimum score to accept bootstrapped demos
max_bootstrapped_demos=4, # Maximum bootstrap examples per predictor
max_labeled_demos=16, # Maximum labeled examples from trainset
max_rounds=1, # Number of bootstrap rounds
max_errors=4, # Max consecutive errors before stopping
)
compiled = teleprompter.compile(student, trainset=trainset)
```
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `metric` | `Callable` | Required | Function comparing expected and predicted values |
| `metric_threshold` | `float` | `None` | Minimum metric score for accepting bootstrapped demos |
| `teacher_settings` | `dict` | `None` | Settings for the teacher model |
| `max_bootstrapped_demos` | `int` | `4` | Maximum bootstrap demonstrations to include |
| `max_labeled_demos` | `int` | `16` | Maximum labeled examples from training set |
| `max_rounds` | `int` | `1` | Number of bootstrap rounds |
| `max_errors` | `int` | `None` | Maximum consecutive errors before stopping |
### BootstrapFewShotWithRandomSearch
This optimizer extends `BootstrapFewShot` by adding random search over different demonstration configurations. It explores multiple bootstrap configurations and selects the best performing one.
资料来源：[dspy/teleprompt/random_search.py]()
### MIPROv2 (Multi-Instruction Prompt Optimization)
MIPROv2 optimizes both instructions and demonstrations using Bayesian optimization. It treats the instruction template and demonstration selection as hyperparameters to optimize.
**Key Characteristics:**
- Uses Bayesian optimization to efficiently search the space of prompts
- Supports fine-grained control over instruction generation
- Can use a separate prompt model for generating candidate instructions
资料来源：[dspy/teleprompt/mipro_optimizer_v2.py]()
```python
from dspy.teleprompt import MIPROv2
optimizer = MIPROv2(
metric=metric,
num_trials=100, # Number of optimization trials
max_bootstrapped_demos=4,
minibend_size=50,
auto="medium", # Automatic complexity control
)
compiled = optimizer.compile(student, trainset=trainset, valset=valset)
```
### COPRO (Coordinate Prompt Optimization)
COPRO generates new prompt instructions iteratively, using a prompt model to propose variations based on the history of previous prompts.
**Algorithm Parameters:**
| Parameter | Default | Description |
|-----------|---------|-------------|
| `breadth` | `10` | Number of new prompts to generate at each iteration |
| `depth` | `3` | Number of iterations to generate new prompts |
| `init_temperature` | `1.4` | Temperature for generation (higher = more creative) |
| `track_stats` | `False` | Whether to track optimization statistics |
资料来源：[dspy/teleprompt/copro_optimizer.py:20-35]()
```python
from dspy.teleprompt import COPRO
teleprompter = COPRO(
prompt_model=prompt_model,
metric=metric,
breadth=10,
depth=3,
init_temperature=1.4,
)
compiled = teleprompter.compile(program, trainset=trainset)
```
### GEPA (Generalized Evolutionary Prompt Algorithm)
GEPA implements reflective prompt evolution using evolutionary strategies. It can outperform reinforcement learning approaches for prompt optimization.
资料来源：[dspy/teleprompt/gepa/gepa.py]()
```python
from dspy.teleprompt import GEPA
optimizer = GEPA(
metric=metric,
auto="medium", # Automatic complexity control
num_trials=50,
)
compiled = optimizer.compile(student, trainset=trainset)
```
### GRPO (Group Relative Policy Optimization)
GRPO applies group relative policy optimization for instruction tuning. It uses a collection of candidate prompts and selects based on relative performance rankings.
资料来源：[dspy/teleprompt/grpo.py]()
## Weight Optimizers
Weight optimizers fine-tune the weights of the language model itself (or adapter weights) to improve program performance.
### BootstrapFinetune
`BootstrapFinetune` uses bootstrapped demonstrations to fine-tune the language model weights. Unlike prompt-only optimization, this method modifies the actual model parameters.
**Requirements:**
- Student programs must have LMs explicitly set via `set_lm()` (not relying on global `dspy.settings.lm`)
- Requires a training set with high-quality demonstrations
资料来源：[dspy/teleprompt/bootstrap_finetune.py]()
```python
from dspy.teleprompt import BootstrapFinetune
optimizer = BootstrapFinetune(metric=metric)
student.set_lm(lm) # Required: explicit LM setting
compiled = optimizer.compile(student, trainset=trainset)
```
## Meta-Optimizers
Meta-optimizers combine multiple optimization strategies into a unified compilation pipeline.
### BetterTogether
`BetterTogether` is a meta-optimizer that orchestrates multiple optimizers in sequence. It separates optimization into distinct phases:
- **Prompt Optimization Phase (p)**: Optimizes instructions and demonstrations
- **Weight Optimization Phase (w)**: Fine-tunes model weights
**Execution Strategy:**
The optimizer uses a strategy string to define execution order:
```mermaid
graph LR
A[Input Program] --> B["Strategy: 'p -> w'"]
B --> C[Prompt Optimizer
e.g., GEPA/MIPROv2]
C --> D[Weight Optimizer
BootstrapFinetune]
D --> E[Compiled Program]
```
资料来源：[dspy/teleprompt/bettertogether.py:1-50]()
```python
from dspy.teleprompt import BetterTogether, GEPA, BootstrapFinetune
# Combine GEPA for prompt optimization with BootstrapFinetune for weights
optimizer = BetterTogether(
metric=metric,
p=GEPA(metric=metric, auto="medium"),
w=BootstrapFinetune(metric=metric),
)
student.set_lm(lm) # Required for weight optimization
compiled = optimizer.compile(
student,
trainset=trainset,
valset=valset,
strategy="p -> w", # Execute prompt optimization, then weight optimization
)
```
| Parameter | Type | Description |
|-----------|------|-------------|
| `metric` | `Callable` | Evaluation metric (required) |
| `optimizers` | `dict[str, Teleprompter]` | Mapping of optimizer names to optimizer instances |
| `strategy` | `str` | Execution strategy (e.g., "p -> w", "p -> w -> p") |
**Optimizer-Specific Arguments:**
You can pass custom arguments to individual optimizers via `optimizer_compile_args`:
```python
compiled = optimizer.compile(
student,
trainset=trainset,
valset=valset,
strategy="p -> w",
optimizer_compile_args={
"p": {"num_trials": 10, "max_bootstrapped_demos": 8},
}
)
```
## Ensemble
The Ensemble teleprompter combines predictions from multiple compiled programs using voting or other aggregation strategies.
资料来源：[dspy/teleprompt/ensemble.py]()
```python
from dspy.teleprompt import Ensemble
# Combine multiple compiled programs
ensemble = Ensemble(metric=metric)
combined = ensemble.compile(
[program1, program2, program3],
trainset=trainset,
)
```
## Bootstrap Tracing
`BootstrapFewShot` and related optimizers rely on `bootstrap_trace.py` to collect demonstrations by executing programs and recording successful traces.
资料来源：[dspy/teleprompt/bootstrap_trace.py]()
**Trace Collection Process:**
1. Execute the student program on each training example
2. Record input/output pairs for each predictor
3. Accept traces that exceed the metric threshold
4. Store demonstrations for inclusion in compiled prompts
## Optimization Workflow
The typical workflow for using optimizers in DSPy:
```mermaid
graph TD
A[Define Program
dspy.Module] --> B[Prepare Training Set
list of Examples]
B --> C[Define Metric
evaluation function]
C --> D[Select Optimizer
BootstrapFewShot/MIPROv2/etc.]
D --> E[Compile Program
optimizer.compile]
E --> F[Evaluate on Test Set
dspy.Evaluate]
subgraph "During Compilation"
G[Generate Candidates
instructions/demos/weights]
H[Evaluate Candidates
using metric]
I[Select Best
update program]
G --> H --> I
end
F --> J{H满意?}
J -->|Yes| K[Deploy Program]
J -->|No| L[Adjust Parameters
retry with different config]
L --> D
```
## Choosing an Optimizer
| Use Case | Recommended Optimizer |
|----------|----------------------|
| Quick baseline with few examples | `BootstrapFewShot` |
| Large training sets, efficient search | `MIPROv2` |
| Evolutionary prompt improvement | `GEPA` |
| Weight fine-tuning alongside prompts | `BetterTogether` with `BootstrapFinetune` |
| Combining multiple compiled programs | `Ensemble` |
| Batch evaluation with random sampling | `BootstrapFewShotWithRandomSearch` |
## Best Practices
1. **Start with BootstrapFewShot**: It's the simplest and often effective baseline for getting started.
2. **Use validation sets**: When available, provide a `valset` parameter to allow the optimizer to select the best program among iterations.
3. **Set LMs explicitly for weight optimization**: Call `student.set_lm(lm)` before compiling with optimizers like `BootstrapFinetune`.
4. **Monitor metric threshold**: Adjust `metric_threshold` to control the quality of bootstrapped demonstrations.
5. **Consider multi-phase optimization**: For best results, use `BetterTogether` to combine prompt and weight optimization.
## Module Exports
All optimizers are exported from `dspy.teleprompt`:
```python
from dspy.teleprompt import (
# Base and utilities
Teleprompter,
BootstrapFewShot,
BootstrapFewShotWithRandomSearch,
# Prompt optimizers
MIPROv2,
COPRO,
GEPA,
GRPO,
# Weight optimizers
BootstrapFinetune,
# Meta-optimizers
BetterTogether,
# Ensemble
Ensemble,
)
```
## See Also
- [Signatures](signatures.md) - How to define input/output schemas for modules
- [Modules](modules.md) - Building programs with Predict, ChainOfThought, and other modules
- [Evaluation](evaluation.md) - Evaluating compiled programs
- [Examples](examples.md) - Working with Example objects
---
---
## Doramagic 踩坑日志
项目：stanfordnlp/dspy
摘要：发现 19 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：PythonInterpreter: paths containing commas are silently misparsed by Deno's --allow-read。
## 1. 安全/权限坑 · 来源证据：PythonInterpreter: paths containing commas are silently misparsed by Deno's --allow-read
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：PythonInterpreter: paths containing commas are silently misparsed by Deno's --allow-read
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_43291e191b234ac883662982bf693e18 | https://github.com/stanfordnlp/dspy/issues/9749 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：3.0.4b1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：3.0.4b1
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_76f47f2d6cbc4f299fe2a852b20617ef | https://github.com/stanfordnlp/dspy/releases/tag/3.0.4b1 | 来源类型 github_release 暴露的待验证使用条件。
## 3. 安装坑 · 来源证据：3.1.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：3.1.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3733e2d7817440638629959030da2ddb | https://github.com/stanfordnlp/dspy/releases/tag/3.1.2 | 来源类型 github_release 暴露的待验证使用条件。
## 4. 安装坑 · 来源证据：3.1.3
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：3.1.3
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2b7f0c4a046840b4b453167ce581b80a | https://github.com/stanfordnlp/dspy/releases/tag/3.1.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：3.2.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：3.2.0
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_976a3edffce44ac3984c9da4a10a2575 | https://github.com/stanfordnlp/dspy/releases/tag/3.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 6. 安装坑 · 来源证据：Use Tool functions that require external libaries in CodeAct
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Use Tool functions that require external libaries in CodeAct
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3c605227d53e42b69651c46c3e76c162 | https://github.com/stanfordnlp/dspy/issues/8839 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:587050620 | https://github.com/stanfordnlp/dspy | README/documentation is current enough for a first validation pass.
## 8. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:587050620 | https://github.com/stanfordnlp/dspy | last_activity_observed missing
## 9. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:587050620 | https://github.com/stanfordnlp/dspy | no_demo; severity=medium
## 10. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:587050620 | https://github.com/stanfordnlp/dspy | no_demo; severity=medium
## 11. 安全/权限坑 · 来源证据：3.0.4
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：3.0.4
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d192b20b863c476ca31d4ba476cec875 | https://github.com/stanfordnlp/dspy/releases/tag/3.0.4 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 12. 安全/权限坑 · 来源证据：3.0.4b2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：3.0.4b2
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_392f60c647b74a6592f1692bcdc0070f | https://github.com/stanfordnlp/dspy/releases/tag/3.0.4b2 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 13. 安全/权限坑 · 来源证据：3.1.0
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：3.1.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_364bbccd7d4241c9b6841303fefb5a85 | https://github.com/stanfordnlp/dspy/releases/tag/3.1.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 14. 安全/权限坑 · 来源证据：3.1.0b1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：3.1.0b1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4599cbf0d1fd41b4b3c47e5c1aae247a | https://github.com/stanfordnlp/dspy/releases/tag/3.1.0b1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 15. 安全/权限坑 · 来源证据：3.1.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：3.1.1
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5656ac7c80214b9fb410d129ccec33d2 | https://github.com/stanfordnlp/dspy/releases/tag/3.1.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 16. 安全/权限坑 · 来源证据：3.2.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：3.2.1
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e2250d3118a04c5e8d213eb2fce4e68d | https://github.com/stanfordnlp/dspy/releases/tag/3.2.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 17. 安全/权限坑 · 来源证据：[Bug] PythonInterpreter fails with default setup due to missing Deno read permissions for Pyodide
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] PythonInterpreter fails with default setup due to missing Deno read permissions for Pyodide
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_bb4eb14c9ce944f0a7654217c34b1d1d | https://github.com/stanfordnlp/dspy/issues/9501 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 18. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:587050620 | https://github.com/stanfordnlp/dspy | issue_or_pr_quality=unknown
## 19. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:587050620 | https://github.com/stanfordnlp/dspy | release_recency=unknown