DSPy: The framework for programming—not prompting—language models
Python
2
Omar Khattabbed52acffacd
diff --git a/docs/building-blocks/2-modules.md b/docs/building-blocks/2-modules.mdindex b9ca09443..ad057d2bc 100644--- a/docs/building-blocks/2-modules.md+++ b/docs/building-blocks/2-modules.md@@ -6,11 +6,119 @@ sidebar_position: 3A **DSPy module** is a building block for programs that use LMs.-- Each built-in module abstracts a **prompting technique** (like chain of thought or ReAct). Crucially, they are generalized to handle any [DSPy Signature]().+- Each built-in module abstracts a **prompting technique** (like chain of thought or ReAct). Crucially, they are generalized to handle any [DSPy Signature].- A DSPy module has **learnable parameters** (i.e., the little pieces comprising the prompt and the LM weights) and can be invoked (called) to process inputs and return outputs.- Multiple modules can be composed into bigger modules (programs). DSPy modules are inspired directly by NN modules in PyTorch, but applied to LM programs.-## How do I use a built-in module?+### How do I use a built-in module, like `dspy.Predict` or `dspy.ChainOfThought`?++Let's start with the most fundamental module, `dspy.Predict`. Internally, all other DSPy modules are just built using `dspy.Predict`.++We'll assume you are already at least a little familiar with [DSPy signatures], which are declarative specs for defining the behavior of any module we use in DSPy.++To use a module, we first **declare** it by giving it a signature. Then we **call** the module with the input arguments, and extract the output fields!++```python+sentence = "it's a charming and often affecting journey." # example from the SST-2 dataset.++# 1) Declare with a signature.+classify = dspy.Predict('sentence -> sentiment')++# 2) Call with input argument(s).+response = classify(sentence=sentence)++# 3) Access the output.+print(response.sentiment)+```+**Output:**+```text+Positive+```++When we declare a module, we can pass configuration keys to it.++Below, we'll pass `n=5` to request five completions. We can also pass `temperature` or `max_len`, etc.++Let's use `dspy.ChainOfThought`. In many cases, simply swapping `dspy.ChainOfThought` in place of `dspy.Predict` improves quality.++```python+question = "What's something great about the ColBERT retrieval model?"++# 1) Declare with a signature, and pass some config.+classify = dspy.ChainOfThought('question -> answer', n=5)++# 2) Call with input argument.+response = classify(question=question)++# 3) Access the outputs.+response.completions.answer+```+**Output:**+```text+['One great thing about the ColBERT retrieval model is its superior efficiency and effectiveness compared to other models.',+ 'Its ability to efficiently retrieve relevant information from large document collections.',+ 'One great thing about the ColBERT retrieval model is its superior performance compared to other models and its efficient use of pre-trained language models.',+ 'One great thing about the ColBERT retrieval model is its superior efficiency and accuracy compared to other models.',+ 'One great thing about the ColBERT retrieval model is its ability to incorporate user feedback and support complex queries.']+```++Let's dicuss the output object here.++The `dspy.ChainOfThought` module will generally inject a `rationale` before the output field(s) of your signature.++Let's inspect the (first) rationale and answer!++```python+print(f"Rationale: {response.rationale}")+print(f"Answer: {response.answer}")+```+**Output:**+```text+Rationale: produce the answer. We can consider the fact that ColBERT has shown to outperform other state-of-the-art retrieval models in terms of efficiency and effectiveness. It uses contextualized embeddings and performs document retrieval in a way that is both accurate and scalable.+Answer: One great thing about the ColBERT retrieval model is its superior efficiency and effectiveness compared to other models.+```++This is accessible whether we request one or many completions.++We can also access the different completions as a list of `Prediction`s or as several lists, one for each field.++```python+response.completions[3].rationale == response.completions.rationale[3]+```+**Output:**+True+++## What other DSPy modules are there? How can I use them?++The others are very similar. They mainly change the internal behavior with which your signature is implemented!++1. **`dspy.Predict`**:++2. **`dspy.ChainOfThought`**:++3. **`dspy.ProgramOfThought`**:++4. **`dspy.ReAct`**:++5. **`dspy.MultiChainComparison`**:+++We also have some function-style modules:++6. **`dspy.majority`**:+++More example soon!+++## How do I compose multiple modules into a bigger program?++DSPy is just Python code that uses modules in any control flow you like. (There's some magic internally at `compile` time to trace your LM calls.)++What this means is that, you can just call the modules freely. No weird abstractions for chaining calls.++This is basically PyTorch's design approach for define-by-run / dynamic computation graphs. Refer to the intro tutorials for examples.