纲要
- 项目准备:开发资源获取
Python与VSCode环境配置- 大模型
API Key获取(兼容 OpenAI 格式的云服务) GitHub Copilot开启 AI 辅助编程- 钉钉开放平台应用创建与
Stream模式配置 LangSmith可观测性追踪开通
- 项目架构概览
- 目录结构
- 核心模块关系(
Mermaid流程图)
- 实战开发:从入口到智能体
- 环境依赖与
Poetry管理 .env配置文件详解- 日志系统初始化
- 钉钉
WebSocket入口实现 - 智能体核心类
AIAgent- 主/备模型回退机制
- 工具加载与记忆系统
- 情感分析与动态提示词
- 多用户记忆隔离(
session_id)
- 完整可运行代码示例
- 环境依赖与
- 总结与相关度说明
项目准备:资源一站式获取
在动手编写代码之前,需要将开发环境、模型 API、钉钉应用等资源全部准备就绪。
| 资源类型 | 获取方式 | 用途 |
|---|---|---|
Python 3.10+ | python.org 下载安装 | 运行环境 |
VSCode | code.visualstudio.com 下载 | 主力 IDE |
GitHub Copilot | VSCode 内购订阅 | AI 辅助编码与调试 |
| 大模型 API | 兼容 OpenAI 格式的云服务(如硅基流动) | 提供 LLM 推理能力 |
搜索引擎 SerpAPI | serpapi.com 注册获取免费密钥 | 在线搜索工具 |
| 钉钉应用 | open.dingtalk.com 创建“钉钉应用” | 消息收发、日程待办 API |
LangSmith | smith.langchain.com 注册并创建 API Key | 调用链追踪与成本监控 |
Redis | 本地安装或 Docker 启动 | 会话记忆存储 |
兼容 OpenAI 格式的 API 服务使用要点
目前主流的国产大模型云服务平台(如硅基流动)托管了大量开源模型(DeepSeek、Qwen 等),其 API 地址完全兼容 OpenAI 格式,只需更换 base_url 即可。注册并完成实名认证后,在“模型广场”中复制模型名称(如 deepseek-ai/DeepSeek-R1),然后在 API 文档 中获取接口地址和密钥。计费透明,按 token 消费,适合个人开发者。
海外模型聚合平台则整合了 OpenAI、Claude、Gemini、DeepSeek 等模型,通过统一接口提供。需注意不同模型的 base_url 后缀可能不同(例如 OpenAI 使用 /v1,Claude 使用 /anthropic)。在“密钥管理”页面创建密钥,并在使用时指定正确的地址。
安全提醒:永远不要将 API Key 明文写在代码中,应放入
.env文件并用.gitignore排除。
项目架构一览
本示例中的智能助手是一个基于 LangChain 的单智能体,通过钉钉 Stream 模式(WebSocket)与用户实时交互,具备日程管理、待办创建、知识库问答和情绪检测能力。其核心架构如下:
用户消息经钉钉 WebSocket 传入后,被入口函数捕获,提取文本和发送者唯一 ID。AIAgent 实例首先分析情绪,据此动态调整提示词,然后调用绑定了工具与记忆的 AgentExecutor,最终生成回复并返回给用户。
实战开发:从零编写核心代码
环境初始化与项目结构
使用 Poetry 管理依赖,确保环境干净可复现。在项目根目录执行:
mkdir xiaolang-dingtalk && cd xiaolang-dingtalk
poetry init -n
poetry add langchain langchain-openai langchain-community python-dotenv redis pydantic \
dingtalk-stream chromadb tiktoken
项目目录结构如下:
xiaolang-dingtalk/
├── src/
│ ├── dingtalk_hook.py # 钉钉入口,WebSocket 回调
│ ├── agent.py # AI智能体核心类
│ ├── tools/
│ │ ├── __init__.py
│ │ ├── calendar.py # 钉钉日历工具
│ │ ├── task.py # 钉钉待办工具
│ │ ├── knowledge.py # RAG 知识库检索
│ │ └── search.py # 在线搜索
│ ├── chains/
│ │ └── emotion.py # 情感检测链
│ └── memory/
│ └── redis_memory.py # Redis 记忆封装
├── .env # 环境变量(不提交仓库)
├── pyproject.toml
└── README.md
配置环境变量 .env
# LLM 主模型
OPENAI_API_KEY=sk-xxxx
OPENAI_BASE_URL=https://api.siliconflow.cn/v1
DEFAULT_MODEL=deepseek-ai/DeepSeek-R1
# 备用模型
DEEPSEEK_API_KEY=sk-xxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
# 搜索引擎
SERPAPI_API_KEY=xxxx
# Redis
REDIS_URL=redis://localhost:6379/0
# 钉钉应用
DINGTALK_APP_KEY=dingxxxx
DINGTALK_APP_SECRET=xxxx
DINGTALK_ROBOT_CODE=xxxx
# LangSmith 追踪
LANGCHAIN_TRACING_V2=true
LANGCHAIN_API_KEY=ls__xxxx
LANGCHAIN_PROJECT=xiaolang-dingtalk
入口文件:钉钉消息接收与回复
使用钉钉官方 dingtalk-stream 库建立 WebSocket 连接,注册消息回调。这里提供一个简化示例,不依赖真实钉钉环境也能本地运行——通过标准输入模拟消息收发,但完整保留了多用户记忆隔离、调用智能体的真实流程。实际部署时,只需将模拟部分替换为 DingTalkStreamClient 即可。
# src/dingtalk_hook.py
import os
import sys
import logging
from dotenv import load_dotenv
from agent import AIAgent
load_dotenv()
# 配置日志
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger("XiaoLang")
# 全局用户存储,模拟从钉钉回调中获取的 sender_id
user_store = {}
def get_or_create_user(sender_id: str):
if sender_id not in user_store:
user_store[sender_id] = {"id": sender_id}
return user_store[sender_id]
def main():
logger.info("小浪助手启动中...")
agent = AIAgent() # 初始化智能体
print("小浪助手已就绪,输入 'exit' 退出。")
# 模拟多用户交互:输入格式为 "用户ID: 消息内容"
while True:
try:
raw = input("> ")
if raw.lower() == "exit":
break
if ":" not in raw:
print("请输入 '用户ID: 消息内容'")
continue
sender_id, text = raw.split(":", 1)
sender_id = sender_id.strip()
text = text.strip()
# 存储或获取用户信息
get_or_create_user(sender_id)
# 调用智能体
reply = agent.run_agent(text, sender_id)
print(f"小浪助手 -> {sender_id}: {reply}")
except KeyboardInterrupt:
break
except Exception as e:
logger.error(f"处理消息失败: {e}")
if __name__ == "__main__":
main()
真实钉钉连接时,将 main 函数替换为 DingTalkStreamClient 的回调注册即可,原理完全一致。
智能体核心类 AIAgent
这个类封装了模型加载、工具注册、记忆管理、情感分析和动态提示词合成的全部逻辑。
# src/agent.py
import os
import json
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain.tools import tool
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.memory import ConversationBufferMemory
from langchain_community.chat_message_histories import RedisChatMessageHistory
from langchain_core.runnables import ConfigurableField
load_dotenv()
# ---------- 工具定义(简化示例) ----------
@tool
def create_calendar_event(summary: str, start_time: str, end_time: str) -> str:
"""创建钉钉日程。参数 summary: 标题, start_time: 开始时间 ISO格式, end_time: 结束时间 ISO格式"""
# 实际调用钉钉 API,此处模拟成功
return f"已创建日程「{summary}」,时间 {start_time} ~ {end_time}"
@tool
def create_task(content: str, priority: str = "normal") -> str:
"""创建钉钉待办。参数 content: 待办内容, priority: 优先级 low/medium/high"""
return f"已创建待办「{content}」,优先级 {priority}"
@tool
def web_search(query: str) -> str:
"""在线搜索最新信息"""
from langchain_community.utilities import SerpAPIWrapper
search = SerpAPIWrapper()
return search.run(query)
tools = [create_calendar_event, create_task, web_search]
# ---------- 情感分析链 ----------
emotion_prompt = ChatPromptTemplate.from_template(
"分析用户消息的情绪,返回JSON: {\"emotion\": \"positive/neutral/negative\", \"score\": 0-10}\n"
"消息: {input}\nJSON:"
)
class AIAgent:
def __init__(self):
# 1. 主模型(可回退到备用模型)
primary = ChatOpenAI(
model=os.getenv("DEFAULT_MODEL", "gpt-3.5-turbo"),
openai_api_key=os.getenv("OPENAI_API_KEY"),
base_url=os.getenv("OPENAI_BASE_URL"),
temperature=0
)
fallback = ChatOpenAI(
model="deepseek-chat",
openai_api_key=os.getenv("DEEPSEEK_API_KEY"),
base_url=os.getenv("DEEPSEEK_BASE_URL"),
temperature=0
)
self.llm = primary.with_fallbacks([fallback])
# 2. 基础记忆系统(用于配置占位,实际运行时会替换为用户专属记忆)
self.base_memory = ConversationBufferMemory(
memory_key="chat_history",
return_messages=True,
input_key="input",
output_key="output"
)
# 3. 情感分析 LLM
self.emotion_llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
# 4. 基础提示词(动态部分通过占位符注入)
base_prompt = ChatPromptTemplate.from_messages([
("system", "你是小浪助手,一个钉钉智能客服。你可以管理日程、创建待办、在线搜索。"
"请友好专业地回复。当前用户情绪状态:{emotion_state}"),
MessagesPlaceholder("chat_history"),
("human", "{input}"),
MessagesPlaceholder("agent_scratchpad")
])
self.base_prompt = base_prompt
# 5. 构建可配置记忆的 Agent
agent = create_tool_calling_agent(self.llm, tools, base_prompt)
self.agent_executor = AgentExecutor(
agent=agent,
tools=tools,
memory=self.base_memory,
verbose=True,
handle_parsing_errors=True,
).configurable_fields(
memory=ConfigurableField(
id="agent_memory",
name="Memory",
description="可切换的记忆实例"
)
)
def detect_emotion(self, text: str) -> dict:
"""调用 LLM 分析情绪,返回 dict"""
chain = emotion_prompt | self.emotion_llm
result = chain.invoke({"input": text})
try:
return json.loads(result.content)
except:
return {"emotion": "neutral", "score": 5}
def get_memory_for_user(self, user_id: str) -> ConversationBufferMemory:
"""为特定用户创建独立的 Redis 记忆"""
history = RedisChatMessageHistory(
session_id=user_id,
url=os.getenv("REDIS_URL", "redis://localhost:6379/0")
)
return ConversationBufferMemory(
memory_key="chat_history",
chat_memory=history,
return_messages=True,
input_key="input",
output_key="output"
)
def run_agent(self, user_input: str, user_id: str = "default") -> str:
# 情绪分析
emotion = self.detect_emotion(user_input)
# 根据情绪值动态调整提示词中的状态描述
if emotion["emotion"] == "negative" and emotion["score"] >= 8:
emotion_state = "强烈负面,请主动将用户诉求创建为高优先级待办"
else:
emotion_state = f"{emotion['emotion']} (分值 {emotion['score']})"
# 合成带情绪状态的提示词
dynamic_prompt = self.base_prompt.partial(emotion_state=emotion_state)
# 重建 agent(因为提示词变化,需要新 agent)
from langchain.agents import create_tool_calling_agent
agent = create_tool_calling_agent(self.llm, tools, dynamic_prompt)
# 获取用户专属记忆
user_memory = self.get_memory_for_user(user_id)
executor = AgentExecutor(
agent=agent,
tools=tools,
memory=user_memory,
verbose=True,
handle_parsing_errors=True,
)
response = executor.invoke({"input": user_input})
return response["output"]
运行效果
确保本地 Redis 已启动,然后执行:
cd src
python dingtalk_hook.py
按提示输入 user1: 帮我创建一个明天下午3点的会议,主题是 AI 进展,智能体将调用工具并回复。不同用户 ID 的消息会拥有各自独立的上下文记忆,互不干扰。
参考文档
官方文档
参考链接
总结
本文从零开始,带领读者完成了钉钉智能助手项目的资源申请、环境搭建和核心代码编写。完整展现了如何利用 LangChain 构建一个支持多工具调用、记忆隔离、情绪感知和模型回退的单智能体,所有代码均可直接复制运行。
主要技术栈要点如下:
- LangChain:作为核心框架,提供
AgentExecutor、ChatPromptTemplate、ConversationBufferMemory等组件,简化了 LLM 应用开发。 - 模型调用与回退:通过
ChatOpenAI统一调用兼容 OpenAI 格式的 API,并使用with_fallbacks实现主备模型自动切换,提升系统鲁棒性。 - 记忆系统:基于
RedisChatMessageHistory实现会话历史持久化,通过session_id区分不同用户,做到多用户记忆隔离。 - 工具集成:利用
@tool装饰器将自定义函数(日程创建、待办管理、网络搜索)注册为 LangChain 工具,供智能体调用。 - 情感分析:通过独立的
ChatPromptTemplate调用 LLM 分析用户情绪,并动态调整系统提示词,使回复更具同理心。 - 可观测性:通过配置
LangSmith,可以追踪每次调用的完整链路、耗时和 token 消耗,便于调试和成本控制。
下一步,可以继续扩展工具集、接入真实钉钉 Stream 回调,或迁移到 LangGraph 实现更复杂的多智能体协作。
521



被折叠的 条评论
为什么被折叠?



