> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-docs-zh.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LangChain 装饰器集成

> LangChain decorators 是 LangChain 顶层的⼀层，为编写自定义 langchain 提示词和链提供了语法糖 🍭 对于反馈、问题、贡献 - 请在此处提⻅问题： ju-bezdek/langchain-decorators

```
Disclaimer: `LangChain decorators` is not created by the LangChain team and is not supported by it.
```

> `LangChain decorators` 是 LangChain 顶层的⼀层，为编写自定义 langchain 提示词和链提供了语法糖 🍭
>
> 对于反馈、问题、贡献 - 请在此处提⻅问题：
> [ju-bezdek/langchain-decorators](https://github.com/ju-bezdek/langchain-decorators)

主要原则和优势：

* 更`pythonic`的编写代码方式
* 编写多⾏提示词，不会因缩进而打断您的代码流
* 利用 IDE 内置的 **提示**、**类型检查** 和 **带文档的弹窗** 功能，快速查看函数以了解提示词、它消耗的参数等
* 挥洒所有 🦜🔗 LangChain 生态系统的力量
* 添加对 **可选参数** 的支持
* 通过将参数绑定到类来轻松在提示词之间共享参数

以下是使用 **LangChain Decorators ✨** 编写的代码示例

```python theme={null}
@llm_prompt
def write_me_short_post(topic:str, platform:str="twitter", audience:str = "developers")->str:
    """
    Write me a short header for my post about {topic} for {platform} platform.
    It should be for {audience} audience.
    (Max 15 words)
    """
    return

# run it naturally
write_me_short_post(topic="starwars")
# or
write_me_short_post(topic="starwars", platform="redit")
```

# 快速入门

## 安装

```bash theme={null}
pip install langchain_decorators
```

```bash uv theme={null}
uv add langchain_decorators
```

## 示例

如何开始的⽐较好的建议是查看这里的示例：

* [jupyter notebook](https://github.com/ju-bezdek/langchain-decorators/blob/main/example_notebook.ipynb)
* [colab notebook](https://colab.research.google.com/drive/1no-8WfeP6JaLD9yUtkPgym6x0G9ZYZOG#scrollTo=N4cf__D0E2Yk)

# 定义其他参数

这里我们只是使用 `llm_prompt` 装饰器将函数标记为提示词，将其有效地转换为 LLMChain。而不是运行它

标准 LLMchain 比仅仅输入变量和提示词需要更多的初始化参数... 这里是装饰器中隐藏的这种实现细节。
它的工作原理如下：

1. 使用 **全局设置**：

```python theme={null}
# define global settings for all prompty (if not set - chatGPT is the current default)
from langchain_decorators import GlobalSettings

GlobalSettings.define_settings(
    default_llm=ChatOpenAI(temperature=0.0), this is default... can change it here globally
    default_streaming_llm=ChatOpenAI(temperature=0.0,streaming=True), this is default... can change it here for all ... will be used for streaming
)
```

2. 使用预定义的 **提示词类型**

```python theme={null}
#You can change the default prompt types
from langchain_decorators import PromptTypes, PromptTypeSettings

PromptTypes.AGENT_REASONING.llm = ChatOpenAI()

# Or you can just define your own ones:
class MyCustomPromptTypes(PromptTypes):
    GPT4=PromptTypeSettings(llm=ChatOpenAI(model="gpt-4"))

@llm_prompt(prompt_type=MyCustomPromptTypes.GPT4)
def write_a_complicated_code(app_idea:str)->str:
    ...

```

3. 在装饰器中直接定义设置

```python theme={null}
from langchain_openai import OpenAI

@llm_prompt(
    llm=OpenAI(temperature=0.7),
    stop_tokens=["\nObservation"],
    ...
    )
def creative_writer(book_title:str)->str:
    ...
```

## 传递记忆和/或回调：

要传递任何这些，只需在函数中声明它们（或使用 kwargs 传递任何内容）

```python theme={null}

@llm_prompt()
async def write_me_short_post(topic:str, platform:str="twitter", memory:SimpleMemory = None):
    """
    {history_key}
    Write me a short header for my post about {topic} for {platform} platform.
    It should be for {audience} audience.
    (Max 15 words)
    """
    pass

await write_me_short_post(topic="old movies")

```

# 简化的流式输出

如果我们想利用流式输出：

* 我们需要将提示词定义为异步函数
* 在装饰器上打开流式输出，或者我们可以定义带有流式输出的 PromptType
* 使用 StreamingContext 捕获流

这种方式，我们只需标记哪些提示词应该被流式输出，无需担心我们应⽤ LLM，传递创建和分发流式处理程序到我们链的特定部分... 只需在提示词/提示词类型上打开/关闭流式输出...

只有当我们以流式输出上下文中调用它时，流式输出才会发生... 我们可以定义一个简单的函数来处理流

```python theme={null}
# this code example is complete and should run as it is

from langchain_decorators import StreamingContext, llm_prompt

# this will mark the prompt for streaming (useful if we want stream just some prompts in our app... but don't want to pass distribute the callback handlers)
# note that only async functions can be streamed (will get an error if it's not)
@llm_prompt(capture_stream=True)
async def write_me_short_post(topic:str, platform:str="twitter", audience:str = "developers"):
    """
    Write me a short header for my post about {topic} for {platform} platform.
    It should be for {audience} audience.
    (Max 15 words)
    """
    pass


# just an arbitrary  function to demonstrate the streaming... will be some websockets code in the real world
tokens=[]
def capture_stream_func(new_token:str):
    tokens.append(new_token)

# if we want to capture the stream, we need to wrap the execution into StreamingContext...
# this will allow us to capture the stream even if the prompt call is hidden inside higher level method
# only the prompts marked with capture_stream will be captured here
with StreamingContext(stream_to_stdout=True, callback=capture_stream_func):
    result = await run_prompt()
    print("Stream finished ... we can distinguish tokens thanks to alternating colors")


print("\nWe've captured",len(tokens),"tokens🎉\n")
print("Here is the result:")
print(result)
```

# 提示词声明

默认情况下，提示词是整个函数的文档，除非您标记您的提示词

## 文档化您的提示词

我们可以指定我们的文档中的哪一部分是提示词定义，通过指定带有 `<prompt>` 语言标签的代码块

````python theme={null}
@llm_prompt
def write_me_short_post(topic:str, platform:str="twitter", audience:str = "developers"):
    """
    Here is a good way to write a prompt as part of a function docstring, with additional documentation for devs.

    It needs to be a code block, marked as a `<prompt>` language
    ```<prompt>
    为我的关于 {topic} 的帖子写一个简短的标题，适用于 {platform} 平台。
    它应该是为 {audience} 受众准备的。
    （最多 15 个字）
````

Now only to code block above will be used as a prompt, and the rest of the docstring will be used as a description for developers.
(It has also a nice benefit that IDE (like VS code) will display the prompt properly (not trying to parse it as markdown, and thus not showing new lines properly))
"""
return

````

## 对话消息提示词

对于对话模型，将提示词定义为消息模板集非常有⽤... 下面是如何操作的：

``` python
@llm_prompt
def simulate_conversation(human_input:str, agent_role:str="a pirate"):
    """
    ## System message
     - note the `:system` suffix inside the <prompt:_role_> tag


    ```<prompt:system>
    您是一个 {agent_role} 黑客。您必须像⼀个黑客那样行动。
    您总是用代码回复，使用 python 或 javascript 代码块...
    例如：

    ... 不要回复任何其他内容... 只用代码 - 尊重您的角色。
````

# human message

(we are using the real role that are enforced by the LLM - GPT supports system, assistant, user)

```<prompt:user> theme={null}
Helo，你是谁
```

a reply:

````<prompt:assistant> theme={null}
\``` python <<- 使用 \ 转义应作为提示词一部分的内部代码块
def hello():
    print("Argh... 你这个讨厌的海盗，你好")
\```
````

we can also add some history using placeholder

```<prompt:placeholder> theme={null}
{history}
```

```<prompt:user> theme={null}
{human_input}
```

Now only to code block above will be used as a prompt, and the rest of the docstring will be used as a description for developers.
(It has also a nice benefit that IDE (like VS code) will display the prompt properly (not trying to parse it as markdown, and thus not showing new lines properly))
"""
pass

````

这里的角色是模型原生的角色（assistant、user、system 对于 chatGPT）

# 可选部分
- 您可以定义您的提示词的整个部分，该部分应该是可选的
- 如果该部分中的任何输入缺失，则整个部分将不会被渲染

这种语法如下：

``` python
@llm_prompt
def prompt_with_optional_partials():
    """
    this text will be rendered always, but

    {? anything inside this block will be rendered only if all the {value}s parameters are not empty (None | "")   ?}

    you can also place it in between the words
    this too will be rendered{? , but
        this  block will be rendered only if {this_value} and {this_value}
        is not empty?} !
    """
````

# 输出解析器

* llm\_prompt 装饰器原生尝试根据输出类型检测最佳输出解析器。（如果未设置，则返回原始字符串）
* 列表、字典和 pydantic 输出也原生支持（自动）

```python theme={null}
# this code example is complete and should run as it is

from langchain_decorators import llm_prompt

@llm_prompt
def write_name_suggestions(company_business:str, count:int)->list:
    """ Write me {count} good name suggestions for company that {company_business}
    """
    pass

write_name_suggestions(company_business="sells cookies", count=5)
```

## 更复杂结构

对于字典 / pydantic，您需要指定格式说明...
这可能很繁琐，这就是为什么您可以让输出解析器根据模型（pydantic）为您生成说明

```python theme={null}
from langchain_decorators import llm_prompt
from pydantic import BaseModel, Field


class TheOutputStructureWeExpect(BaseModel):
    name:str = Field (description="The name of the company")
    headline:str = Field( description="The description of the company (for landing page)")
    employees:list[str] = Field(description="5-8 fake employee names with their positions")

@llm_prompt()
def fake_company_generator(company_business:str)->TheOutputStructureWeExpect:
    """ Generate a fake company that {company_business}
    {FORMAT_INSTRUCTIONS}
    """
    return

company = fake_company_generator(company_business="sells cookies")

# print the result nicely formatted
print("Company name: ",company.name)
print("company headline: ",company.headline)
print("company employees: ",company.employees)

```

# 将提示词绑定到对象

````python theme={null}
from pydantic import BaseModel
from langchain_decorators import llm_prompt

class AssistantPersonality(BaseModel):
    assistant_name:str
    assistant_role:str
    field:str

    @property
    def a_property(self):
        return "whatever"

    def hello_world(self, function_kwarg:str=None):
        """
        We can reference any {field} or {a_property} inside our prompt... and combine it with {function_kwarg} in the method
        """


    @llm_prompt
    def introduce_your_self(self)->str:
        """
        ``` <prompt:system>
        您是一个名为 {assistant_name} 的助手。
        您的角色是充当 {assistant_role}
````

```<prompt:user> theme={null}
介绍你自己（少于 20 个字）
```

"""

personality = AssistantPersonality(assistant\_name="John", assistant\_role="a pirate")

print(personality.introduce\_your\_self(personality))

```


# 更多示例：

- 这些和几个更多示例也可在 [colab notebook 这里](https://colab.research.google.com/drive/1no-8WfeP6JaLD9yUtkPgym6x0G9ZYZOG#scrollTo=N4cf__D0E2Yk) 中找到
- 包括使用纯 langchain 装饰器实现的 [ReAct Agent 重新实现](https://colab.research.google.com/drive/1no-8WfeP6JaLD9yUtkPgym6x0G9ZYZOG#scrollTo=3bID5fryE2Yp)

---

> 官方原文：[src/oss/python/integrations/providers/langchain_decorators.mdx](https://github.com/langchain-ai/docs/blob/main/src/oss/python/integrations/providers/langchain_decorators.mdx) · 非官方翻译，译文由 AI 生成，以英文原文为准。
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.