Agent 记忆、规划与多步任务:从 Demo 到可靠系统

Demo 里 Agent「看起来很聪明」,上线后却常翻车:忘上下文、死循环调工具、中途跑偏。要把 Demo 做成可靠系统,得补齐记忆、规划、约束三块。

记忆分层

  • 短期记忆:当前会话 messages
  • 情景记忆:向量库存历史对话摘要
  • 长期偏好:用户设置、权限、常用工具
# 会话过长时做摘要压缩
if token_count(messages) > 6000:
    summary = summarize(messages[:-4])
    messages = [{"role": "system", "content": summary}] + messages[-4:]

规划:先拆任务再执行

plan_prompt = """
把用户目标拆成最多 5 个可执行步骤,输出 JSON 数组。
用户目标:{goal}
"""
steps = parse_json(llm(plan_prompt))
for step in steps:
    observe = run_agent_step(step)
    # 每步校验,失败则重规划

可靠性护栏

  1. 最大步数 / 最大工具调用次数
  2. 工具白名单与参数校验
  3. 关键写操作二次确认(人工 in-the-loop)
  4. 完整 trace:每一步输入、工具、输出都落日志

评估怎么做

准备 30~50 个真实任务集:成功标准、允许工具、期望最终答案。每次改 Prompt/工具都回归一遍。没有评估集,Agent 优化只能靠感觉。

一句话总结:Agent 的核心不是更会聊,而是可控地完成任务。

用 LangChain / 自研框架搭一个能查库的 Agent

很多教程一上来堆框架。其实你也可以自研一个「LLM + 工具注册表 + 循环」的小内核。本文给两种路线:自研最小核,以及 LangChain 快速拼装。

自研最小核

TOOL_REGISTRY = {}

def tool(name, desc, schema):
    def deco(fn):
        TOOL_REGISTRY[name] = {"fn": fn, "desc": desc, "schema": schema}
        return fn
    return deco

@tool("sql_query", "只读查询业务库", {"sql": "string"})
def sql_query(sql: str) -> str:
    assert sql.strip().lower().startswith("select")
    # 执行只读 SQL 并返回 markdown 表
    return run_readonly_sql(sql)

关键安全:Agent 查库默认只读账号,并拦截非 SELECT。

LangChain 思路(概念)

# 伪代码
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.tools import tool

@tool
def get_course_price(course_name: str) -> str:
    """查询课程价格"""
    return query_price(course_name)

agent = create_tool_calling_agent(llm, [get_course_price], prompt)
executor = AgentExecutor(agent=agent, tools=[get_course_price])
print(executor.invoke({"input": "Python爬虫课多少钱?"}))

什么时候自研 / 用框架

  • 学习原理、控制力要求高 → 自研小核
  • 快速验证、工具多、链路长 → 框架更省事
  • 上线后都要补:超时、重试、轨迹日志、人工接管

Agent 是什么:工具调用(Function Calling)工作流拆解

Chatbot 只会聊天;Agent 还能决定调用工具:查库、搜文档、算数、调 API。理解 Function Calling,是进入 Agent 开发的第一扇门。

一次典型循环

  1. 用户提出目标
  2. 模型选择:直接回答 or 调用某个工具
  3. 程序执行工具,把结果回填
  4. 模型基于工具结果继续推理,直到给出最终答案

工具描述示例

tools = [{
  "type": "function",
  "function": {
    "name": "get_order",
    "description": "根据订单号查询订单状态与金额",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": {"type": "string", "description": "订单号"}
      },
      "required": ["order_id"]
    }
  }
}]

伪代码主循环

messages = [{"role": "user", "content": "帮我查订单 A10086 到哪了"}]
while True:
    resp = llm.chat(messages, tools=tools)
    if resp.tool_calls:
        for call in resp.tool_calls:
            result = run_tool(call.name, call.arguments)
            messages.append({"role": "tool", "tool_call_id": call.id, "content": result})
        continue
    return resp.content

设计原则

  • 工具要少而精,描述写清楚「何时用」
  • 参数 schema 严格,减少胡编参数
  • 工具执行必须鉴权与审计

RAG 入门:向量检索 + 大模型问答流水线

大模型不会自动知道你的课程文档和内部 wiki。RAG(检索增强生成)的思路是:先检索相关片段,再让模型基于片段回答,从而降低幻觉、可追溯来源。

流水线五步

  1. 文档切分(chunk)
  2. 向量化(embedding)
  3. 写入向量库
  4. 用户提问 → 检索 Top-K
  5. 把片段塞进 Prompt 生成答案

最小逻辑伪代码

chunks = split_docs(docs, size=500, overlap=80)
vectors = embed(chunks)
index.upsert(vectors)

def answer(question: str) -> str:
    q_vec = embed([question])[0]
    hits = index.search(q_vec, top_k=5)
    context = "\n\n".join(h.text for h in hits)
    prompt = f"基于以下资料回答,若资料不足请说不知道:\n{context}\n\n问题:{question}"
    return chat([{"role": "user", "content": prompt}])

效果关键点

  • 切分太大:检索不准;太小:缺上下文
  • Top-K 不是越大越好,噪声会干扰回答
  • 回答时要求「引用资料编号」,便于人工核对

什么时候上 RAG

  • 知识经常更新(课程、公告、文档)
  • 需要可追溯,不能纯靠模型记忆
  • 垂直领域术语多

先用本地几篇 Markdown 跑通闭环,再上生产向量库。

用 OpenAI 兼容接口调用 DeepSeek / 通义等模型

现在很多国产模型都提供OpenAI 兼容的 Chat Completions 接口。一套代码,换 base_url 和 model 就能切换供应商。

通用调用模板

import os
import requests

API_URL = os.getenv("LLM_API_URL", "https://api.deepseek.com/chat/completions")
API_KEY = os.getenv("LLM_API_KEY")
MODEL = os.getenv("LLM_MODEL", "deepseek-chat")

def chat(messages, temperature=0.2):
    resp = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "model": MODEL,
            "messages": messages,
            "temperature": temperature,
        },
        timeout=60,
    )
    resp.raise_for_status()
    return resp.json()["choices"][0]["message"]["content"]

answer = chat([
    {"role": "system", "content": "你是简洁的中文技术助教"},
    {"role": "user", "content": "用三句话解释什么是向量数据库"},
])
print(answer)

工程注意点

  • 密钥只放环境变量 / 密钥管理,不进 Git
  • 设置超时、重试、限流
  • 记录 token 消耗,方便成本核算
  • 对用户输入做长度限制,防超上下文

流式输出(SSE)场景

聊天产品常用 stream 模式边生成边展示。先把非流式跑稳,再加流式,排错成本更低。

切换模型时测什么

  1. 同样 Prompt 的格式遵守率
  2. 中文术语准确性
  3. 长上下文是否截断
  4. 价格与延迟

Prompt 工程:让大模型稳定输出结构化结果

同样一个模型,提示词写得好不好,效果能差一个数量级。做产品时,目标往往是:稳定产出可解析的 JSON/Markdown,而不是一次漂亮的散文。

好 Prompt 的骨架

  1. 角色:你是谁
  2. 任务:要干什么
  3. 约束:不能干什么
  4. 格式:输出长什么样
  5. 示例:给 1~2 个正例

示例:抽取简历关键字段

你是信息抽取助手。从用户文本中提取字段,只输出 JSON,不要解释。
字段:name, years, skills(array), summary
若缺失请填 null。

示例输入:张三,5年Python,擅长爬虫与数据分析。
示例输出:{"name":"张三","years":5,"skills":["Python","爬虫","数据分析"],"summary":"5年Python开发"}

现在处理:
"""
{{用户文本}}
"""

提高稳定性的技巧

  • 要求「只输出 JSON」,并在代码里做解析重试
  • 把枚举值写死:状态只能是 A/B/C
  • 复杂任务拆成多步:先分类,再抽取,再校验
  • 关键业务加规则校验(日期格式、金额范围)

Python 侧校验

import json
from jsonschema import validate

schema = {
  "type": "object",
  "required": ["name", "skills"],
  "properties": {
    "name": {"type": ["string", "null"]},
    "skills": {"type": "array", "items": {"type": "string"}},
  },
}

def parse_llm_json(text: str):
    data = json.loads(text)
    validate(data, schema)
    return data

模型负责生成,代码负责验收——这是上线级 Prompt 工程的核心。

Nginx 反向代理与 Docker 部署 Web 应用入门

本地 python app.py 能跑,不代表能上线。生产环境通常是:Docker 跑应用 + Nginx 对外反代。本文给你最小可用图景。

为什么需要 Nginx

  • 统一 80/443 入口,后端不直接暴露
  • 静态资源缓存、HTTPS 终结
  • 多服务按域名/路径分流

反向代理片段

server {
    listen 80;
    server_name demo.example.com;

    location / {
        proxy_pass http://webapp:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Docker Compose 思路

services:
  webapp:
    build: .
    networks: [app-net]
  nginx:
    image: nginx:1.25-alpine
    ports: ["80:80"]
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on: [webapp]
    networks: [app-net]

上线检查清单

  1. 健康检查接口:/health
  2. 日志落盘或收集,方便排错
  3. 密钥走环境变量
  4. 数据库不映射公网端口

你现在的 antpython.net 与博客,就是「同网桥 + Nginx 按域名反代」的典型结构。

RESTful API 设计要点与常见错误

前后端分离后,API 就是合同。合同写清楚,联调少吵架。本文总结 REST 设计里最实用的约定和踩坑点。

资源导向,而不是动作导向

# 更 REST
GET    /api/orders
GET    /api/orders/123
POST   /api/orders
PATCH  /api/orders/123
DELETE /api/orders/123

# 不推荐
POST /api/getOrderList
POST /api/deleteOrder

统一响应结构

{
  "code": 0,
  "message": "ok",
  "data": {"id": 123, "status": "paid"}
}

错误时也返回可机读的 code 和人类可读的 message,并配上合适 HTTP 状态码(400/401/403/404/500)。

分页、过滤、排序

GET /api/orders?status=paid&page=1&page_size=20&sort=-created_at

幂等与安全

  • GET 不应改数据
  • 删除/更新要鉴权,防越权(不能只信前端传的 user_id)
  • 创建类接口可加幂等键,避免重复提交

常见错误

  1. 所有接口都返回 200,错误只写在 body
  2. 字段命名中英混用、同一含义多个名字
  3. 没有版本策略,一改全崩(可用 /api/v1)
  4. 文档缺失:至少维护 OpenAPI / 示例请求

Flask 从路由到模板:做一个迷你站点

Flask 轻量、好上手,很适合把 Python 能力接到 Web 上。本文从路由、请求、模板三块搭一个迷你站点骨架。

最小应用

from flask import Flask, render_template, request, redirect, url_for

app = Flask(__name__)

@app.get("/")
def index():
    return render_template("index.html", title="首页")

@app.route("/hello/<name>")
def hello(name: str):
    return f"你好,{name}!"

@app.post("/search")
def search():
    q = request.form.get("q", "").strip()
    return render_template("search.html", q=q)

if __name__ == "__main__":
    app.run(debug=True, port=5000)

模板继承

{# templates/base.html #}
<!doctype html>
<title>{% block title %}站点{% endblock %}</title>
<body>
  <nav><a href="{{ url_for('index') }}">首页</a></nav>
  {% block content %}{% endblock %}
</body>
{# templates/index.html #}
{% extends "base.html" %}
{% block title %}首页{% endblock %}
{% block content %}
<h1>欢迎</h1>
{% endblock %}

项目结构建议

myapp/
  app.py
  templates/
  static/
  requirements.txt

下一步

  1. 把业务拆成 Blueprint(用户、文章、后台)
  2. 用 Flask-Session / JWT 做登录态
  3. 配置与密钥走环境变量

先跑通「页面能开、表单能交、模板能复用」,再谈框架对比。

用 Python(PyMySQL/SQLAlchemy)安全操作数据库

用 Python 连 MySQL 时,安全第一原则是:永远不要把用户输入拼进 SQL 字符串。本文给出 PyMySQL 与 SQLAlchemy 的正确姿势。

PyMySQL 参数化查询

import pymysql

conn = pymysql.connect(
    host="127.0.0.1",
    user="app",
    password="***",
    database="demo",
    charset="utf8mb4",
    cursorclass=pymysql.cursors.DictCursor,
)

def get_user(user_id: int):
    sql = "SELECT id, name, email FROM users WHERE id=%s"
    with conn.cursor() as cur:
        cur.execute(sql, (user_id,))
        return cur.fetchone()

# 错误示范:f-string 拼接,有 SQL 注入风险
# cur.execute(f"SELECT * FROM users WHERE id={user_id}")

批量插入

rows = [("Alice", "a@x.com"), ("Bob", "b@x.com")]
sql = "INSERT INTO users(name, email) VALUES (%s, %s)"
with conn.cursor() as cur:
    cur.executemany(sql, rows)
conn.commit()

SQLAlchemy 核心写法(简版)

from sqlalchemy import create_engine, text

engine = create_engine("mysql+pymysql://app:***@127.0.0.1:3306/demo?charset=utf8mb4")

with engine.begin() as conn:
    result = conn.execute(
        text("SELECT * FROM users WHERE city=:city"),
        {"city": "北京"},
    )
    for row in result.mappings():
        print(row)

工程实践清单

  • 连接信息放环境变量,不写进仓库
  • 生产库账号最小权限(不要随便用 root)
  • 读写超时、连接池、失败重试要有
  • 变更数据必须事务:成功 commit,失败 rollback