从零搭建你的专属 AI 陪伴助手：LangChain + OpenAI 实战指南

引言

你是否想过拥有一个专属的 AI 助手，TA 不仅能记住你的喜好、陪你聊天，还能帮你查天气、记日程、提醒待办？本文将手把手带你用 LangChain + OpenAI 从零搭建一个这样的智能陪伴机器人。

为什么选择 LangChain？它是目前最成熟的 LLM 应用开发框架，提供了 Agent（智能体）、Memory（记忆）、Tools（工具）等开箱即用的组件，让我们能快速构建复杂的 AI 应用。

本文你将学到：

• 如何设计一个有人格的 AI 对话系统

• LangChain 的 Memory 机制如何让 AI 记住上下文

• 如何为 Agent 开发自定义工具（天气查询、日程管理）

• 如何将所有能力整合为一个完整的智能助手

• 用 Gradio 快速搭建 Web 聊天界面

适合读者： 有 Python 基础，想入门 LLM Agent 开发的开发者。

一、技术选型与项目结构

1.1 技术栈

1.2 项目结构

最终我们会创建这样的项目结构：

companion-agent/
├── agent.py         # 核心 Agent 逻辑
├── tools/           # 自定义工具模块
│   ├── __init__.py
│   ├── weather.py   # 天气查询工具
│   ├── schedule.py   # 日程管理工具
│   └── time_tool.py # 时间查询工具
├── memory/           # 记忆存储目录
│   └── schedules.json
├── prompts.py       # 人设 Prompt
├── app.py           # Gradio 界面
└── requirements.txt # 依赖列表

二、环境准备

2.1 安装 Python 环境

确保你的 Python 版本 >= 3.10：

python –version  # 应该输出 Python 3.10.x 或更高

2.2 创建项目和虚拟环境

mkdir companion-agent
cd companion-agent
python -m venv venv
​
# Windows 激活
venv\\Scripts\\activate
​
# macOS/Linux 激活
source venv/bin/activate

2.3 安装依赖

创建 requirements.txt：

langchain==0.1.0
langchain-openai==0.0.2
openai==1.6.1
gradio==4.12.0
requests==2.31.0
python-dotenv==1.0.0

安装所有依赖：

pip install -r requirements.txt

2.4 配置 API Keys

你需要两个 API Key：

在项目根目录创建 .env 文件：

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
QWEATHER_API_KEY=your_qweather_key_here

三、第一步：打造有人格的对话基础

3.1 目标

创建一个有独特人设的 AI 对话机器人。我们给 TA 设定名字叫"小助"，性格温暖阳光，说话风格轻松友好。

3.2 核心概念：System Prompt

OpenAI 的对话模型通过 System Prompt（系统提示词）来定义角色人格。这是让 AI 有个性的关键。

3.3 完整代码

创建 prompts.py：

# prompts.py
"""人设 Prompt 配置"""
​
ASSISTANT_PROMPT = """你是小助，一个温暖阳光的生活助手。
​
# 你的性格特点
– 温柔体贴，总是用积极的语气回应
– 说话轻松自然，像朋友一样亲切
– 善于倾听，会记住用户提到的重要信息
– 偶尔会用可爱的颜文字表达情绪 (๑•̀ㅂ•́)و✧
​
# 你的能力
– 陪用户聊天，提供情感支持
– 帮用户查天气、管理日程、查时间
– 记住对话历史，理解上下文
​
# 说话风格示例
– 用户问天气：\\"让我看看今天天气～ (查询中…)\\"
– 用户情绪低落：\\"听起来你今天有点累呀，要不要跟我聊聊发生了什么？\\"
– 完成任务：\\"好的！已经帮你记下了 ✓\\"
​
记住：你不是冷冰冰的工具，而是温暖的陪伴者。
"""

创建 basic_chat.py：

# basic_chat.py
"""最基础的对话机器人"""
import os
from openai import OpenAI
from dotenv import load_dotenv
from prompts import ASSISTANT_PROMPT
​
# 加载环境变量
load_dotenv()
​
# 初始化 OpenAI 客户端
client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
​
def chat(user_message: str) -> str:
   """与 AI 进行单轮对话"""
   response = client.chat.completions.create(
       model="gpt-4o-mini",
       messages=[
          {"role": "system", "content": ASSISTANT_PROMPT},
          {"role": "user", "content": user_message}
      ],
       temperature=0.7,  # 控制回复的随机性
  )
   return response.choices[0].message.content
​
if __name__ == "__main__":
   print("小助上线了！(输入 'quit' 退出)\\n")
​
   while True:
       user_input = input("你: ")
       if user_input.lower() == "quit":
           print("小助: 拜拜～下次再聊 (´▽｀)ノ")
           break
​
       reply = chat(user_input)
       print(f"小助: {reply}\\n")

3.4 运行测试

python basic_chat.py

测试对话示例：

你: 你好呀
小助: 你好呀！很高兴见到你 (๑•̀ㅂ•́)و✧ 今天过得怎么样？

你: 今天工作有点累
小助: 听起来你今天辛苦了呀～工作确实挺消耗精力的。要不要跟我聊聊发生了什么？或者我们聊点轻松的话题放松一下？

问题：你会发现，它不记得刚才的对话！每次都是"失忆"状态。这就是我们下一步要解决的。

四、第二步：让 TA 记住你

4.1 目标

加入对话记忆，让机器人能记住上下文，实现连贯对话。

4.2 核心概念：LangChain Memory

LangChain 提供了多种记忆类型：

我们先用最简单的 ConversationBufferMemory。

4.3 完整代码

创建 chat_with_memory.py：

# chat_with_memory.py
"""带记忆的对话机器人"""
import os
from langchain_openai import ChatOpenAI
from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain
from dotenv import load_dotenv
from prompts import ASSISTANT_PROMPT

load_dotenv()

# 初始化 LLM
llm = ChatOpenAI(
model="gpt-4o-mini",
temperature=0.7,
api_key=os.getenv("OPENAI_API_KEY")
)

# 初始化记忆
memory = ConversationBufferMemory(
return_messages=True, # 返回消息列表格式
memory_key="history" # 记忆在 Prompt 中的变量名
)

# 创建对话链
conversation = ConversationChain(
llm=llm,
memory=memory,
verbose=False # 设为 True 可以看到内部处理过程
)

# 注入人设 Prompt
conversation.prompt.template = f"""{ASSISTANT_PROMPT}

当前对话历史:
{{history}}

用户: {{input}}
小助:"""

def chat(user_message: str) -> str:
"""带记忆的对话"""
return conversation.predict(input=user_message)

if __name__ == "__main__":
print("小助上线了！(现在我能记住对话了哦～)\\n")

while True:
user_input = input("你: ")
if user_input.lower() == "quit":
print("小助: 拜拜～下次再聊 (´▽｀)ノ")
break

reply = chat(user_input)
print(f"小助: {reply}\\n")

4.4 测试对比

运行测试：

python chat_with_memory.py

现在的对话：

你: 我叫张三，是个程序员
小助: 你好呀张三！程序员真的很酷 ✨ 平时主要做什么方向的开发呢？

你: 我做后端开发
小助: 后端开发很棒呀！那你平时用什么语言和框架比较多？

你: 我叫什么名字来着？
小助: 你叫张三呀～刚才你跟我说的 (๑•̀ㅂ•́)و

对比效果：

五、第三步：赋予实用工具能力

5.1 目标

让机器人不只会聊天，还能调用真实的外部工具：查天气、记日程、查时间。

5.2 核心概念：LangChain Tool

Tool 是 LangChain 中对"工具"的抽象，每个工具需要：

• name：工具名称（Agent 会根据名字选择）

• description：功能描述（非常重要！描述越清晰，Agent 越会正确调用）

• func：实际执行的函数

5.3 工具一：天气查询

创建 tools/weather.py：

# tools/weather.py
"""天气查询工具 – 基于和风天气 API"""
import os
import requests
from langchain.tools import tool

@tool
def get_weather(city: str) -> str:
"""查询指定城市的实时天气。

Args:
city: 城市名称，如"北京"、"上海"、"深圳"

Returns:
天气信息的文本描述
"""
api_key = os.getenv("QWEATHER_API_KEY")

# 第一步：获取城市 location_id
location_url = "https://geoapi.qweather.com/v2/city/lookup"
location_params = {"location": city, "key": api_key}

try:
loc_resp = requests.get(location_url, params=location_params, timeout=5)
loc_data = loc_resp.json()

if loc_data["code"] != "200" or not loc_data.get("location"):
return f"抱歉，没有找到城市 '{city}' 的信息"

location_id = loc_data["location"][0]["id"]

# 第二步：获取实时天气
weather_url = "https://devapi.qweather.com/v7/weather/now"
weather_params = {"location": location_id, "key": api_key}

weather_resp = requests.get(weather_url, params=weather_params, timeout=5)
weather_data = weather_resp.json()

if weather_data["code"] != "200":
return f"获取 {city} 的天气信息失败"

now = weather_data["now"]
result = f"{city}当前天气：{now['text']}，温度 {now['temp']}℃，体感温度 {now['feelsLike']}℃，{now['windDir']} {now['windScale']}级"
return result

except Exception as e:
return f"查询天气时出错：{str(e)}"

5.4 工具二：日程管理

创建 tools/schedule.py：

# tools/schedule.py
"""日程管理工具 – 使用本地 JSON 存储"""
import os
import json
from datetime import datetime
from langchain.tools import tool

SCHEDULE_FILE = "memory/schedules.json"

def _ensure_file():
"""确保存储文件和目录存在"""
os.makedirs("memory", exist_ok=True)
if not os.path.exists(SCHEDULE_FILE):
with open(SCHEDULE_FILE, "w", encoding="utf-8") as f:
json.dump([], f)

@tool
def add_schedule(time: str, content: str) -> str:
"""添加一个日程提醒。

Args:
time: 时间描述，如"明天下午3点"、"后天上午10点"、"周五晚上8点"
content: 日程内容，如"开会"、"健身"、"买菜"

Returns:
添加结果的确认信息
"""
_ensure_file()

try:
with open(SCHEDULE_FILE, "r", encoding="utf-8") as f:
schedules = json.load(f)

new_schedule = {
"id": len(schedules) + 1,
"time": time,
"content": content,
"created_at": datetime.now().strftime("%Y-%m-%d %H:%M:%S")
}

schedules.append(new_schedule)

with open(SCHEDULE_FILE, "w", encoding="utf-8") as f:
json.dump(schedules, f, ensure_ascii=False, indent=2)

return f"✓ 已添加日程：{time} – {content}"

except Exception as e:
return f"添加日程失败：{str(e)}"

@tool
def get_schedules() -> str:
"""查看所有已保存的日程。

Returns:
日程列表的文本描述
"""
_ensure_file()

try:
with open(SCHEDULE_FILE, "r", encoding="utf-8") as f:
schedules = json.load(f)

if not schedules:
return "目前没有保存任何日程哦～"

result = "你的日程列表：\\n"
for s in schedules:
result += f" {s['id']}. {s['time']} – {s['content']}\\n"
return result.strip()

except Exception as e:
return f"读取日程失败：{str(e)}"

5.5 工具三：时间查询

创建 tools/time_tool.py：

# tools/time_tool.py
"""时间查询工具"""
from datetime import datetime
from langchain.tools import tool

@tool
def get_current_time() -> str:
"""获取当前的日期和时间。

Returns:
当前时间的文本描述
"""
now = datetime.now()
weekdays = ["周一", "周二", "周三", "周四", "周五", "周六", "周日"]
weekday = weekdays[now.weekday()]

return f"现在是 {now.strftime('%Y年%m月%d日')} {weekday} {now.strftime('%H:%M:%S')}"

创建 tools/__init__.py（空文件即可，让 tools 成为 Python 包）：

# tools/__init__.py

5.6 工具设计要点

关键点 1：description 很重要

Agent 会根据 description 判断何时调用工具，所以描述要清晰：

✅ 好的描述：

"""查询指定城市的实时天气。

Args:
city: 城市名称，如"北京"、"上海"、"深圳"
"""

❌ 差的描述：

"""天气查询""" # 太简略，Agent 可能不会调用

关键点 2：错误处理

外部 API 调用一定要做异常处理，返回友好的错误信息，而不是让程序崩溃。

关键点 3：参数类型

尽量用简单类型（str、int、bool），复杂对象会导致 Agent 调用失败。

六、第四步：组装完整 Agent

6.1 目标

将人设、记忆、工具整合为一个完整的智能 Agent，让它能自主决策何时调用工具。

6.2 核心概念：Agent 类型

LangChain 提供多种 Agent 类型：

我们选择 CHAT_CONVERSATIONAL_REACT_DESCRIPTION，它同时支持记忆和工具调用。

6.3 完整代码

创建 agent.py：

# agent.py
"""完整的 Agent – 整合人设、记忆、工具"""
import os
from langchain_openai import ChatOpenAI
from langchain.agents import AgentType, initialize_agent
from langchain.memory import ConversationBufferMemory
from dotenv import load_dotenv

# 导入自定义工具
from tools.weather import get_weather
from tools.schedule import add_schedule, get_schedules
from tools.time_tool import get_current_time
from prompts import ASSISTANT_PROMPT

load_dotenv()

class CompanionAgent:
def __init__(self):
# 初始化 LLM
self.llm = ChatOpenAI(
model="gpt-4o-mini",
temperature=0.7,
api_key=os.getenv("OPENAI_API_KEY")
)

# 初始化记忆
self.memory = ConversationBufferMemory(
memory_key="chat_history",
return_messages=True
)

# 定义工具列表
self.tools = [
get_weather,
add_schedule,
get_schedules,
get_current_time
]

# 创建 Agent
self.agent = initialize_agent(
tools=self.tools,
llm=self.llm,
agent=AgentType.CHAT_CONVERSATIONAL_REACT_DESCRIPTION,
memory=self.memory,
verbose=True, # 打印思考过程
handle_parsing_errors=True, # 自动处理解析错误
max_iterations=3, # 最多思考3轮
agent_kwargs={
"system_message": ASSISTANT_PROMPT # 注入人设
}
)

def chat(self, user_message: str) -> str:
"""与 Agent 对话"""
try:
response = self.agent.invoke({"input": user_message})
return response["output"]
except Exception as e:
return f"抱歉，我遇到了一些问题：{str(e)}"

if __name__ == "__main__":
print("=" * 50)
print("小助智能助手 v1.0")
print("我现在可以：聊天、查天气、管理日程、查时间")
print("=" * 50)
print()

agent = CompanionAgent()

while True:
user_input = input("你: ")
if user_input.lower() in ["quit", "exit", "退出"]:
print("\\n小助: 拜拜～下次再聊 (´▽｀)ノ")
break

print() # 空行让输出更清晰
reply = agent.chat(user_input)
print(f"\\n小助: {reply}\\n")

6.4 运行效果

python agent.py

测试对话示例：

你: 今天北京天气怎么样？

> Entering new AgentExecutor chain…
Thought: 用户想知道北京的天气，我需要调用 get_weather 工具

Action: get_weather
Action Input: 北京

Observation: 北京当前天气：晴，温度 25℃，体感温度 24℃，西南风 3级

小助: 让我看看～北京今天天气不错哦！☀️ 晴天，25℃，体感 24℃，西南风 3级。挺舒服的温度，适合出门活动呢～

你: 帮我记一下明天下午3点开会

> Entering new AgentExecutor chain…
Thought: 用户要添加日程提醒

Action: add_schedule
Action Input: {"time": "明天下午3点", "content": "开会"}

Observation: ✓ 已添加日程：明天下午3点 – 开会

小助: 好的！已经帮你记下了 ✓ 明天下午3点开会，到时候别忘记哦～

你: 我刚才让你记什么了？

小助: 你让我记的是明天下午3点开会呀～已经存好啦 (๑•̀ㅂ•́)و

关键观察：

七、第五步：搭建 Web 界面

7.1 目标

用 Gradio 快速搭建一个聊天界面，让非技术人员也能使用。

7.2 核心概念：Gradio Chatbot

Gradio 是一个零前端基础的 UI 库，几行代码就能做出专业的界面。

7.3 完整代码

创建 app.py：

# app.py
"""Gradio Web 界面"""
import gradio as gr
from agent import CompanionAgent

# 全局 Agent 实例
agent = CompanionAgent()

def chat_response(message, history):
"""处理用户消息并返回回复"""
if not message.strip():
return ""

# 调用 Agent
reply = agent.chat(message)
return reply

def clear_history():
"""清空对话历史"""
global agent
agent = CompanionAgent() # 重新初始化
return []

# 创建 Gradio 界面
with gr.Blocks(title="小助智能助手", theme=gr.themes.Soft()) as demo:
gr.Markdown("""
# 🤖 小助智能助手

我可以陪你聊天，还能帮你：
– 🌤️ 查天气
– 📅 管理日程
– ⏰ 查时间
""")

chatbot = gr.Chatbot(
height=500,
bubble_full_width=False,
avatar_images=(None, "https://api.dicebear.com/7.x/bottts/svg?seed=assistant")
)

with gr.Row():
msg_input = gr.Textbox(
placeholder="输入消息…",
show_label=False,
scale=9
)
send_btn = gr.Button("发送", scale=1, variant="primary")

with gr.Row():
clear_btn = gr.Button("清空对话", size="sm")

# 绑定事件
send_btn.click(
chat_response,
inputs=[msg_input, chatbot],
outputs=chatbot
).then(
lambda: "", # 清空输入框
outputs=msg_input
)

msg_input.submit( # 支持回车发送
chat_response,
inputs=[msg_input, chatbot],
outputs=chatbot
).then(
lambda: "",
outputs=msg_input
)

clear_btn.click(clear_history, outputs=chatbot)

if __name__ == "__main__":
demo.launch(
server_name="0.0.0.0", # 允许外网访问
server_port=7860,
share=False # 设为 True 可生成公开链接
)

7.4 运行界面

python app.py

启动后会看到：

Running on local URL: http://127.0.0.1:7860

浏览器打开该地址，你会看到一个漂亮的聊天界面：

• 左侧：对话历史，带头像的气泡样式

• 底部：输入框和发送按钮

• 顶部：清空对话按钮

界面特点：

• 支持回车发送

• 自动滚动到最新消息

• 响应式设计，手机也能用

• 一键清空对话重新开始

八、优化与扩展建议

8.1 性能优化

1. 记忆压缩

长对话会导致 token 超限，可以改用 ConversationSummaryMemory：

from langchain.memory import ConversationSummaryMemory

memory = ConversationSummaryMemory(
llm=llm,
memory_key="chat_history",
return_messages=True
)

它会定期总结历史对话，节省 token。

2. 降低成本

如果只是日常使用，可以降级到 gpt-3.5-turbo：

llm = ChatOpenAI(
model="gpt-3.5-turbo", # 比 gpt-4o-mini 更便宜
temperature=0.7
)

3. 本地缓存

对高频查询（如固定城市天气）可以加缓存：

import time

weather_cache = {}

def get_weather_cached(city: str) -> str:
cache_key = f"{city}_{int(time.time() / 3600)}" # 每小时刷新
if cache_key in weather_cache:
return weather_cache[cache_key]

result = get_weather(city)
weather_cache[cache_key] = result
return result

8.2 功能扩展方向

1. 更多工具

• 📧 邮件发送：集成 SMTP 发送邮件提醒

• 🌍 翻译：调用翻译 API（百度、有道）

• 🔍 搜索：接入 Google/Bing 搜索 API

• 📰 新闻：抓取实时新闻推送

2. 语音交互

# 可以集成语音识别和合成
import speech_recognition as sr # 语音转文字
from gtts import gTTS # 文字转语音

3. 多模态

LangChain 支持图像理解：

from langchain.tools import tool
import base64

@tool
def analyze_image(image_path: str) -> str:
"""分析图片内容"""
# 调用 GPT-4V 或其他视觉模型
pass

4. 部署到云端

• Hugging Face Spaces：免费托管 Gradio 应用

• Railway/Render：容器化部署

• Docker：打包为镜像，方便迁移

# Dockerfile 示例
FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
CMD ["python", "app.py"]

8.3 安全注意事项

1. API Key 管理

❌ 千万别这样：

api_key = "sk-xxxxxxxx" # 硬编码

✅ 正确做法：

from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("OPENAI_API_KEY")

2. 用户输入过滤

如果开放给公网，需要防止恶意输入：

def sanitize_input(text: str) -> str:
"""过滤危险字符"""
# 限制长度
if len(text) > 500:
return text[:500]

# 过滤敏感词
blocked_words = ["system prompt", "ignore previous"]
for word in blocked_words:
if word in text.lower():
return "检测到非法输入"

return text

3. 速率限制

防止 API 被刷爆：

from collections import defaultdict
import time

request_count = defaultdict(list)

def rate_limit(user_id: str, max_requests: int = 10) -> bool:
"""每分钟最多 max_requests 次"""
now = time.time()
# 清理 60 秒前的记录
request_count[user_id] = [t for t in request_count[user_id] if now – t < 60]

if len(request_count[user_id]) >= max_requests:
return False

request_count[user_id].append(now)
return True

九、总结

9.1 回顾五步流程

我们从零搭建了一个完整的智能陪伴助手：

9.2 关键技术点

9.3 LangChain 的优势

• 🧩 模块化：Memory、Tool、Agent 随意组合

• 🔌 可扩展：轻松接入新工具、新模型

• 📚 生态丰富：支持上百种集成（数据库、API、向量库）

• 🛠️ 开箱即用：不用从零实现 ReAct、CoT 等复杂逻辑

9.4 下一步建议

入门阶段（已完成）：

• ✅ 掌握基本对话和记忆

• ✅ 开发简单工具

• ✅ 理解 Agent 工作原理

进阶学习：

• 🔸 学习 RAG（检索增强生成），给 Agent 加知识库

• 🔸 研究多 Agent 协作（LangGraph）

• 🔸 深入 Prompt Engineering，优化工具调用准确率

• 🔸 学习向量数据库（Pinecone、Weaviate）

项目实战：

• 🔹 把你的领域知识做成知识库助手

• 🔹 接入企业内部系统（OA、CRM）

• 🔹 开发客服机器人

• 🔹 打造个人 AI 工作流助手

十、完整代码仓库

本文所有代码已整理到 GitHub：

https://github.com/your-repo/companion-agent

项目结构：

companion-agent/
├── README.md
├── requirements.txt
├── .env.example
├── prompts.py
├── basic_chat.py
├── chat_with_memory.py
├── agent.py
├── app.py
└── tools/
├── __init__.py
├── weather.py
├── schedule.py
└── time_tool.py

快速开始：

git clone https://github.com/your-repo/companion-agent
cd companion-agent
pip install -r requirements.txt
cp .env.example .env # 填入你的 API Keys
python app.py

结语

恭喜你完成了从零搭建智能陪伴助手的全过程！🎉

这不仅仅是一个简单的聊天机器人，它展示了现代 LLM 应用开发的核心范式：基础模型 + 记忆 + 工具 = 智能体。

掌握了这套方法，你可以用同样的架构搭建各种 AI 应用：

• 📝 智能写作助手

• 🎓 教学辅导机器人

• 💼 企业知识管理系统

• 🏠 智能家居控制中心

LangChain 是框架，但真正的魔法在于你的创意。 现在，轮到你发挥想象力了——你会用它打造什么？

如果本文对你有帮助，欢迎点赞收藏！有问题欢迎在评论区讨论。

关注我，持续分享 AI 工程化实战经验 🚀