AI Agent 部署完整教程｜附完整命令

随着大模型能力的不断增强，越来越多企业和开发者开始将 AI Agent（智能体） 应用到客服、数据分析、自动化办公、研发辅助、知识库问答、运维巡检等场景中。相比单纯调用大模型接口，AI Agent 更强调“自主规划、工具调用、记忆管理、任务执行和结果反馈”，因此部署一个可用、稳定、可扩展的 AI Agent 系统，通常需要同时考虑模型、框架、向量数据库、工具服务、API 网关、权限、安全、日志和监控等多个环节。

本文将从零开始，带你完成一个 AI Agent 的部署流程。教程尽量采用通用方案，适合个人开发者、小团队和企业内部试点项目参考。文中会给出完整命令，方便你直接复制执行。

一、什么是 AI Agent？

AI Agent 可以理解为一个具备任务执行能力的智能系统。它不仅能够与用户对话，还可以根据目标自动拆解任务、调用工具、读取知识库、执行代码、访问数据库或第三方 API，并最终给出结果。

一个典型 AI Agent 通常包括以下模块：

二、部署方案选择

本文采用一个相对清晰、易维护的部署架构：

用户
 |
 | HTTP / WebSocket
 v
前端页面 / API 调用方
 |
 v
FastAPI 后端服务
 |
 |-- LangChain / LangGraph Agent 框架
 |-- OpenAI / 兼容 OpenAI API 的大模型
 |-- Chroma 向量数据库
 |-- 本地工具函数
 |-- Redis 会话缓存（可选）
 |
 v
返回结果

本教程使用的主要技术栈如下：

如果你使用的是阿里云百炼、智谱、DeepSeek、Kimi、通义千问、火山方舟、Azure OpenAI 或本地 Ollama，只要接口兼容 OpenAI Chat Completions 格式，也可以较容易地替换。

三、服务器环境准备

1. 推荐配置

用于测试和小规模使用时，建议服务器配置如下：

如果你要本地部署大模型，例如 Qwen、Llama、DeepSeek-R1-Distill 等，则需要更高配置，尤其是 GPU 显存。

2. 更新系统

登录服务器后，先更新系统软件包：

sudo apt update && sudo apt upgrade -y

安装常用工具：

sudo apt install -y curl wget git vim unzip build-essential software-properties-common

查看系统版本：

lsb_release -a

查看 CPU 和内存：

lscpu
free -h
df -h

四、安装 Python 环境

Ubuntu 22.04 默认一般自带 Python 3.10。先检查版本：

python3 --version

如果版本低于 3.10，建议安装新版 Python。这里以 Python 3.10 为例：

sudo apt install -y python3 python3-pip python3-venv

检查 pip：

pip3 --version

创建项目目录：

mkdir -p ~/ai-agent-demo
cd ~/ai-agent-demo

创建虚拟环境：

python3 -m venv venv

激活虚拟环境：

source venv/bin/activate

升级 pip：

pip install --upgrade pip setuptools wheel

五、创建 AI Agent 项目

1. 初始化项目结构

执行以下命令创建目录：

mkdir -p app
mkdir -p data
mkdir -p logs
touch app/__init__.py
touch app/main.py
touch app/agent.py
touch app/tools.py
touch app/config.py
touch requirements.txt
touch .env

项目结构如下：

ai-agent-demo/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── agent.py
│   ├── tools.py
│   └── config.py
├── data/
├── logs/
├── requirements.txt
├── .env
└── venv/

2. 编写依赖文件

编辑 requirements.txt：

vim requirements.txt

写入以下内容：

fastapi==0.115.0
uvicorn[standard]==0.30.6
python-dotenv==1.0.1
pydantic==2.8.2
langchain==0.2.16
langchain-openai==0.1.23
langchain-community==0.2.16
chromadb==0.5.5
tiktoken==0.7.0
requests==2.32.3

安装依赖：

pip install -r requirements.txt

如果安装速度较慢，可以使用国内镜像源：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

六、配置大模型 API

编辑 .env 文件：

vim .env

写入以下配置：

OPENAI_API_KEY=你的API_KEY
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini

APP_HOST=0.0.0.0
APP_PORT=8000

如果你使用的是兼容 OpenAI 格式的国产模型服务，可以类似这样配置：

OPENAI_API_KEY=你的服务商API_KEY
OPENAI_BASE_URL=https://你的模型服务地址/v1
OPENAI_MODEL=你的模型名称

例如 DeepSeek：

OPENAI_API_KEY=你的DeepSeek_API_KEY
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_MODEL=deepseek-chat

例如本地 Ollama OpenAI 兼容接口：

OPENAI_API_KEY=ollama
OPENAI_BASE_URL=http://127.0.0.1:11434/v1
OPENAI_MODEL=qwen2.5:7b

注意：.env 文件中包含密钥，不要提交到 Git 仓库。

七、编写配置模块

编辑 app/config.py：

vim app/config.py

写入以下代码：

import os
from dotenv import load_dotenv

load_dotenv()

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
OPENAI_BASE_URL = os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1")
OPENAI_MODEL = os.getenv("OPENAI_MODEL", "gpt-4o-mini")

APP_HOST = os.getenv("APP_HOST", "0.0.0.0")
APP_PORT = int(os.getenv("APP_PORT", "8000"))

八、编写工具函数

AI Agent 的关键能力之一是调用工具。下面我们先实现几个简单工具：获取当前时间、计算表达式、读取本地知识文本。

编辑 app/tools.py：

vim app/tools.py

写入以下代码：

from datetime import datetime
from langchain.tools import tool


@tool
def get_current_time() -> str:
    """获取当前服务器时间。"""
    return datetime.now().strftime("%Y-%m-%d %H:%M:%S")


@tool
def calculator(expression: str) -> str:
    """计算一个数学表达式，例如：1 + 2 * 3。"""
    try:
        allowed_chars = "0123456789+-*/(). %"
        if not all(char in allowed_chars for char in expression):
            return "表达式包含不允许的字符。"
        result = eval(expression, {"__builtins__": {}})
        return str(result)
    except Exception as e:
        return f"计算失败：{str(e)}"


@tool
def local_knowledge_search(query: str) -> str:
    """搜索本地知识库文本。适合回答公司制度、产品说明、项目文档等问题。"""
    try:
        with open("data/knowledge.txt", "r", encoding="utf-8") as f:
            content = f.read()

        if query in content:
            return content

        lines = content.splitlines()
        matched = [line for line in lines if any(word in line for word in query.split())]

        if matched:
            return "\n".join(matched[:10])

        return "没有在本地知识库中找到相关内容。"
    except FileNotFoundError:
        return "知识库文件不存在，请先创建 data/knowledge.txt。"

这里的 local_knowledge_search 是一个非常简单的示例。在生产环境中，更推荐使用向量数据库进行语义检索，后文会继续介绍。

九、编写 Agent 核心逻辑

编辑 app/agent.py：

vim app/agent.py

写入以下代码：

from langchain_openai import ChatOpenAI
from langchain.agents import create_tool_calling_agent, AgentExecutor
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from app.config import OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL
from app.tools import get_current_time, calculator, local_knowledge_search


def create_agent_executor():
    llm = ChatOpenAI(
        api_key=OPENAI_API_KEY,
        base_url=OPENAI_BASE_URL,
        model=OPENAI_MODEL,
        temperature=0.3,
    )

    tools = [
        get_current_time,
        calculator,
        local_knowledge_search,
    ]

    prompt = ChatPromptTemplate.from_messages([
        (
            "system",
            "你是一个专业、可靠的 AI Agent。"
            "你可以根据用户问题自主选择是否调用工具。"
            "回答时要清晰、准确、结构化。"
            "如果不知道答案，不要编造，应说明不确定。"
        ),
        ("human", "{input}"),
        MessagesPlaceholder(variable_name="agent_scratchpad"),
    ])

    agent = create_tool_calling_agent(
        llm=llm,
        tools=tools,
        prompt=prompt,
    )

    executor = AgentExecutor(
        agent=agent,
        tools=tools,
        verbose=True,
        max_iterations=5,
        handle_parsing_errors=True,
    )

    return executor


agent_executor = create_agent_executor()


def run_agent(user_input: str) -> str:
    result = agent_executor.invoke({"input": user_input})
    return result.get("output", "")

十、编写 FastAPI 服务

编辑 app/main.py：

vim app/main.py

写入以下代码：

from fastapi import FastAPI
from pydantic import BaseModel
from app.agent import run_agent
from app.config import APP_HOST, APP_PORT

app = FastAPI(
    title="AI Agent Demo",
    description="一个基于 FastAPI 和 LangChain 的 AI Agent 服务",
    version="1.0.0",
)


class ChatRequest(BaseModel):
    message: str


class ChatResponse(BaseModel):
    answer: str


@app.get("/")
def root():
    return {
        "message": "AI Agent service is running.",
        "docs": "/docs"
    }


@app.get("/health")
def health():
    return {
        "status": "ok"
    }


@app.post("/chat", response_model=ChatResponse)
def chat(req: ChatRequest):
    answer = run_agent(req.message)
    return ChatResponse(answer=answer)


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(
        "app.main:app",
        host=APP_HOST,
        port=APP_PORT,
        reload=True,
    )

十一、准备知识库文件

创建一个简单知识库：

cat > data/knowledge.txt << 'EOF'
公司名称：星河智能科技有限公司。
办公时间：周一至周五，上午 9:00 到下午 6:00。
报销制度：员工需要在费用发生后 30 天内提交报销申请，并上传发票。
年假制度：工作满一年后可享受 5 天带薪年假，工作年限越长年假天数越多。
产品名称：AgentFlow，是一款面向企业的 AI Agent 自动化平台。
产品功能：支持知识库问答、工作流编排、API 调用、数据分析和自动报告生成。
技术支持邮箱：support@example.com。
EOF

十二、本地启动测试

在项目根目录执行：

source venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

如果启动成功，你会看到类似输出：

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.

在服务器本机测试健康接口：

curl http://127.0.0.1:8000/health

预期返回：

{"status":"ok"}

测试 Agent 对话接口：

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"现在几点？"}'

测试计算工具：

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"请帮我计算 128 * 36 + 99"}'

测试知识库：

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"公司的报销制度是什么？"}'

也可以访问接口文档：

http://服务器IP:8000/docs

十三、加入向量数据库知识库检索

上面的本地文本搜索比较简单，无法很好地处理语义相近的问题。下面加入 Chroma 向量数据库，实现基础 RAG 检索能力。

1. 创建向量库脚本

新建文件：

touch app/vector_store.py
vim app/vector_store.py

写入以下代码：

from langchain_community.vectorstores import Chroma
from langchain_openai import OpenAIEmbeddings
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.document_loaders import TextLoader
from app.config import OPENAI_API_KEY, OPENAI_BASE_URL

CHROMA_DIR = "data/chroma_db"


def build_vector_store(file_path: str = "data/knowledge.txt"):
    loader = TextLoader(file_path, encoding="utf-8")
    docs = loader.load()

    splitter = RecursiveCharacterTextSplitter(
        chunk_size=300,
        chunk_overlap=50,
    )
    split_docs = splitter.split_documents(docs)

    embeddings = OpenAIEmbeddings(
        api_key=OPENAI_API_KEY,
        base_url=OPENAI_BASE_URL,
    )

    db = Chroma.from_documents(
        documents=split_docs,
        embedding=embeddings,
        persist_directory=CHROMA_DIR,
    )

    return db


def search_vector_store(query: str, k: int = 3) -> str:
    embeddings = OpenAIEmbeddings(
        api_key=OPENAI_API_KEY,
        base_url=OPENAI_BASE_URL,
    )

    db = Chroma(
        persist_directory=CHROMA_DIR,
        embedding_function=embeddings,
    )

    docs = db.similarity_search(query, k=k)

    if not docs:
        return "没有检索到相关知识。"

    return "\n\n".join([doc.page_content for doc in docs])

2. 创建构建脚本

新建 build_index.py：

touch build_index.py
vim build_index.py

写入：

from app.vector_store import build_vector_store

if __name__ == "__main__":
    build_vector_store()
    print("向量知识库构建完成。")

执行构建：

python build_index.py

如果成功，会在 data/chroma_db 下生成向量数据库文件。

3. 将向量检索加入工具

修改 app/tools.py：

vim app/tools.py

增加以下工具：

from app.vector_store import search_vector_store


@tool
def vector_knowledge_search(query: str) -> str:
    """使用向量数据库搜索本地知识库，适合语义检索。"""
    return search_vector_store(query)

然后在 app/agent.py 中导入并加入工具列表：

from app.tools import get_current_time, calculator, local_knowledge_search, vector_knowledge_search

工具列表改为：

tools = [
    get_current_time,
    calculator,
    local_knowledge_search,
    vector_knowledge_search,
]

重启服务：

pkill -f uvicorn
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

测试语义检索：

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message":"员工多久以内需要提交费用报销？"}'

十四、使用 systemd 后台运行服务

开发环境可以用 uvicorn --reload，但生产环境不建议这样运行。下面使用 systemd 管理服务。

1. 获取项目路径

pwd

假设路径为：

/home/ubuntu/ai-agent-demo

2. 创建 systemd 服务文件

sudo vim /etc/systemd/system/ai-agent.service

写入以下内容，注意将路径和用户替换成你的实际信息：

[Unit]
Description=AI Agent FastAPI Service
After=network.target

[Service]
User=ubuntu
Group=ubuntu
WorkingDirectory=/home/ubuntu/ai-agent-demo
Environment="PATH=/home/ubuntu/ai-agent-demo/venv/bin"
ExecStart=/home/ubuntu/ai-agent-demo/venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

重新加载 systemd：

sudo systemctl daemon-reload

启动服务：

sudo systemctl start ai-agent

设置开机自启：

sudo systemctl enable ai-agent

查看状态：

sudo systemctl status ai-agent

查看日志：

journalctl -u ai-agent -f

重启服务：

sudo systemctl restart ai-agent

停止服务：

sudo systemctl stop ai-agent

十五、配置 Nginx 反向代理

直接暴露 8000 端口并不理想，建议使用 Nginx 做反向代理。

1. 安装 Nginx

sudo apt install -y nginx

查看状态：

sudo systemctl status nginx

2. 创建站点配置

sudo vim /etc/nginx/sites-available/ai-agent

写入：

server {
    listen 80;
    server_name your-domain.com;

    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;

        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;

        proxy_read_timeout 300;
        proxy_connect_timeout 300;
        proxy_send_timeout 300;
    }
}

如果暂时没有域名，可以把 server_name 改成服务器 IP：

server_name 你的服务器IP;

启用配置：

sudo ln -s /etc/nginx/sites-available/ai-agent /etc/nginx/sites-enabled/

检查 Nginx 配置：

sudo nginx -t

重载 Nginx：

sudo systemctl reload nginx

测试访问：

curl http://your-domain.com/health

十六、配置 HTTPS 证书

如果有域名，建议使用 Certbot 申请免费 HTTPS 证书。

安装 Certbot：

sudo apt install -y certbot python3-certbot-nginx

申请证书：

sudo certbot --nginx -d your-domain.com

按提示输入邮箱并确认即可。

测试自动续期：

sudo certbot renew --dry-run

证书申请成功后，你就可以使用：

https://your-domain.com

访问服务。

十七、使用 Docker 部署

除了直接在服务器上部署，也可以使用 Docker，便于迁移和复现。

1. 安装 Docker

curl -fsSL https://get.docker.com | bash

启动 Docker：

sudo systemctl start docker
sudo systemctl enable docker

查看版本：

docker --version

如果希望当前用户免 sudo 使用 Docker：

sudo usermod -aG docker $USER

然后重新登录服务器。

2. 编写 Dockerfile

在项目根目录创建：

vim Dockerfile

写入：

FROM python:3.10-slim

WORKDIR /app

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential curl \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .

RUN pip install --upgrade pip \
    && pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

COPY . .

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

3. 编写 docker-compose.yml

创建文件：

vim docker-compose.yml

写入：

services:
  ai-agent:
    build: .
    container_name: ai-agent
    ports:
      - "8000:8000"
    env_file:
      - .env
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    restart: always

构建镜像：

docker compose build

启动服务：

docker compose up -d

查看容器状态：

docker compose ps

查看日志：

docker compose logs -f

测试接口：

curl http://127.0.0.1:8000/health

停止服务：

docker compose down

重启服务：

docker compose restart

十八、增加简单鉴权

生产环境不建议裸露接口，至少要加一个 API Key 鉴权。

修改 .env：

APP_API_KEY=设置一个复杂的访问密钥

修改 app/config.py：

APP_API_KEY = os.getenv("APP_API_KEY", "")

修改 app/main.py：

from fastapi import FastAPI, Header, HTTPException
from app.config import APP_API_KEY

增加鉴权函数：

def verify_api_key(x_api_key: str = Header(default="")):
    if APP_API_KEY and x_api_key != APP_API_KEY:
        raise HTTPException(status_code=401, detail="Invalid API Key")

修改接口：

@app.post("/chat", response_model=ChatResponse)
def chat(req: ChatRequest, x_api_key: str = Header(default="")):
    verify_api_key(x_api_key)
    answer = run_agent(req.message)
    return ChatResponse(answer=answer)

调用时加请求头：

curl -X POST http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 设置一个复杂的访问密钥" \
  -d '{"message":"请介绍一下 AgentFlow 产品功能"}'

十九、常见问题排查

1. 端口被占用

查看占用端口：

sudo lsof -i:8000

结束进程：

sudo kill -9 进程PID

2. 模型 API 请求失败

检查 .env：

cat .env

确认：

• OPENAI_API_KEY 是否正确；
• OPENAI_BASE_URL 是否正确；
• OPENAI_MODEL 是否存在；
• 服务器是否能访问模型服务。

测试网络：

curl -I https://api.openai.com

3. systemd 服务启动失败

查看日志：

journalctl -u ai-agent -n 100 --no-pager

常见原因：

• WorkingDirectory 路径错误；
• User 用户不存在；
• 虚拟环境路径错误；
• .env 没有被正确读取；
• Python 依赖没有安装完整。

4. Nginx 返回 502

检查后端服务是否运行：

curl http://127.0.0.1:8000/health

检查 Nginx 配置：

sudo nginx -t

查看 Nginx 日志：

sudo tail -f /var/log/nginx/error.log

二十、生产环境优化建议

如果你准备将 AI Agent 用于真实业务，建议进一步优化以下方面：

1. 会话记忆

当前示例是单轮对话。生产环境通常需要保存用户历史消息，可以使用：

• Redis；
• PostgreSQL；
• MySQL；
• MongoDB；
• LangChain Memory；
• LangGraph 状态管理。

2. 工具权限隔离

Agent 可以调用工具，但工具越强大，风险越高。建议：

• 限制可调用工具范围；
• 对危险操作增加人工确认；
• 数据库工具只读优先；
• 文件操作限制目录；
• 外部 API 设置调用频率限制。

3. 日志与审计

需要记录：

• 用户请求；
• Agent 输出；
• 工具调用记录；
• 错误信息；
• token 消耗；
• 请求耗时。

可以结合：

• Python logging；
• ELK；
• Grafana Loki；
• Prometheus；
• OpenTelemetry。

4. 异步和队列

对于耗时任务，例如生成报告、批量分析文件、长时间爬取网页，建议使用异步任务队列：

• Celery；
• Redis Queue；
• Dramatiq；
• Kafka；
• RabbitMQ。

5. 安全防护

AI Agent 容易受到提示词注入、越权访问、数据泄露等风险影响。建议：

• 对用户输入做过滤；
• 对工具输出做安全检查；
• 不把敏感密钥暴露给模型；
• 严格区分系统提示词和用户输入；
• 为接口增加鉴权、限流和日志审计。

二十一、完整启动命令汇总

如果你已经准备好代码，最简启动流程如下：

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-pip python3-venv git curl vim

mkdir -p ~/ai-agent-demo
cd ~/ai-agent-demo

python3 -m venv venv
source venv/bin/activate

pip install --upgrade pip setuptools wheel
pip install -r requirements.txt

python build_index.py

uvicorn app.main:app --host 0.0.0.0 --port 8000

systemd 部署：

sudo systemctl daemon-reload
sudo systemctl start ai-agent
sudo systemctl enable ai-agent
sudo systemctl status ai-agent

Docker 部署：

docker compose build
docker compose up -d
docker compose logs -f

Nginx 部署：

sudo apt install -y nginx
sudo nginx -t
sudo systemctl reload nginx

HTTPS 证书：

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
sudo certbot renew --dry-run

二十二、总结

本文完整介绍了一个 AI Agent 的部署流程，包括服务器环境准备、Python 项目初始化、LangChain Agent 编写、工具调用、FastAPI 接口封装、知识库文件接入、向量数据库检索、systemd 后台运行、Nginx 反向代理、HTTPS 配置、Docker 容器化部署以及生产环境优化建议。

对于个人开发者来说，可以先从本文的最小版本开始：一个 FastAPI 服务、一个大模型接口、几个工具函数、一个知识库文件。等业务场景逐渐清晰后，再逐步加入向量数据库、会话记忆、任务队列、权限控制和监控系统。

真正可用的 AI Agent 不只是“接入一个大模型”，而是要围绕业务流程进行工具设计、上下文管理、权限控制和结果验证。只要架构设计合理、部署流程规范、工具边界清晰，AI Agent 就可以成为企业自动化和智能化升级中的重要基础设施。