项目接入 AI 指南-阿里百炼版（基础用法）

项目接入 AI 开发指南

---

API 快速接入对比示例

DeepSeek 官方 Curl 示例

curl -X POST https://api.deepseek.com/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "Hello, how are you?"}],
    "temperature": 0.7,
    "stream": false
  }'

通义千问（百炼）兼容模式 Curl 示例

阿里云百炼全系列模型兼容 OpenAI 请求协议，可无缝适配各类大模型 SDK。

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "messages": [
        {"role": "system", "content": "你是专业技术助手"},
        {"role": "user", "content": "你是谁？"}
    ],
    "stream": false,
    "temperature": 0.7
}'

---

一、API 密钥申请

通义千问（百炼）密钥获取

1. 访问阿里云百炼控制台完成账号注册与登录；
2. 进入密钥管理页面，手动创建API Key；
3. 权限默认覆盖通用对话、多模态、工具调用能力，直接复制保存。

安全规范：禁止硬编码密钥到代码，统一通过 .env 环境变量、配置中心读取。

---

二、Python 基础接入示例

前置依赖安装

# 基础网络请求
pip install requests
# 环境变量读取
pip install python-dotenv
# OpenAI 兼容SDK
pip install openai

示例1：原生 Requests 自主封装客户端

纯原生 HTTP 请求，无第三方大模型依赖，轻量场景首选。

import requests
import json
import time

class QWenClient:
    def __init__(self, api_key):
        self.api_key = api_key
        # 百炼兼容模式统一地址
        self.base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
    
    def chat(self, messages, model="qwen3-coder-plus", temperature=0.7, stream=False):
        """
        通用对话接口
        :param messages: 会话消息列表
        :param model: 模型名称
        :param temperature: 随机性系数
        :param stream: 是否流式输出
        :return: 完整响应 / 流式生成器
        """
        headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {self.api_key}"
        }
        data = {
            "model": model,
            "messages": messages,
            "temperature": temperature,
            "stream": stream
        }
        try:
            response = requests.post(
                url=f"{self.base_url}/chat/completions",
                headers=headers,
                json=data,
                timeout=60
            )
            response.raise_for_status()  # 捕获4xx/5xx异常
            if not stream:
                return response.json()
            return self.stream_response(response)    
        except Exception as e:
            return {"error": str(e), "detail": response.text if 'response' in locals() else ""}
    
    def stream_response(self, response):
        """流式数据解析器"""
        for line in response.iter_lines():
            if not line:
                continue
            decoded_line = line.decode('utf-8')
            if decoded_line.startswith('data: '):
                data_content = decoded_line[6:]
                if data_content != '[DONE]':
                    yield json.loads(data_content)

# ========== 使用示例 ==========
if __name__ == "__main__":
    client = QWenClient("你的API_KEY")
    messages = [
        {"role": "system", "content": "你是一个有用的AI助手"},
        {"role": "user", "content": "你好，请介绍一下自己"}
    ]

    # 流式输出
    print("AI - 流式输出回复：", end="", flush=True)
    stream_result = client.chat(messages, stream=True)
    for chunk in stream_result:
        try:
            content = chunk['choices'][0]['delta'].get('content', '')
            print(content, end="", flush=True)
            time.sleep(0.02) 
        except Exception:
            continue
    print()

示例2：OpenAI 兼容模式（推荐）

依托官方标准 SDK，代码极简、维护成本低，项目主流接入方案。

1. 项目根目录 .env 配置

# 阿里云百炼配置
ALIYUN_API_KEY=你的实际API_KEY
ALIYUN_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
DEFAULT_MODEL=qwen3.6-plus

2. 业务代码实现（自带会话记忆）

from openai import OpenAI
from dotenv import load_dotenv
import os
import time

# 加载本地环境变量
load_dotenv()

# 初始化兼容模式客户端
client = OpenAI(
    api_key=os.getenv("ALIYUN_API_KEY"),
    base_url=os.getenv("ALIYUN_BASE_URL")
)

# 全局维护会话上下文，实现多轮记忆
messages = [
    {"role": "system", "content": "你是一个专业可靠的AI助手"}
]

# 第一轮对话 - 流式输出
user_input = "你好，请介绍一下自己，200字左右"
messages.append({"role": "user", "content": user_input})

print("AI（流式）：", end="", flush=True)
stream = client.chat.completions.create(
    model=os.getenv("DEFAULT_MODEL"),
    messages=messages,
    stream=True,
    temperature=0.7
)

full_response = ""
for chunk in stream:
    content = chunk.choices[0].delta.content or ""
    if content:
        full_response += content
        print(content, end="", flush=True)
        time.sleep(0.02)
print()

# 追加AI回复，留存历史上下文
messages.append({"role": "assistant", "content": full_response})

# 第二轮对话 - 自动关联历史记忆
print("\n--- 第二轮对话（记忆测试）---")
user_input2 = "我刚才让你做什么了？"
messages.append({"role": "user", "content": user_input2})

resp = client.chat.completions.create(
    model=os.getenv("DEFAULT_MODEL"),
    messages=messages,
    temperature=0.7
)

ai_msg = resp.choices[0].message.content
print("AI：", ai_msg)
messages.append({"role": "assistant", "content": ai_msg})

---

三、核心参数详解

3.1 messages 角色说明

大模型会话标准三元角色，多轮对话必须严格遵循：

角色	字段值	作用场景
system	系统指令	设定AI角色、行为约束、行业规则、输出格式
user	用户提问	业务问题、需求指令、图片/文件输入
assistant	AI回复	模型历史回答，用于上下文记忆拼接

示例：

messages = [
    {"role": "system", "content": "专注Java后端技术解答，回答精简"},
    {"role": "user", "content": "如何优化Redis缓存？"},
    {"role": "assistant", "content": "1.合理设置过期时间 2.避免缓存穿透..."}
]

3.2 temperature 随机性参数

控制模型输出创造力与确定性，按需选型：

• 0.1 ~ 0.3：严谨、重复度低，适合代码生成、数据解析、问答答疑；
• 0.5 ~ 0.7：均衡模式，日常对话、文案撰写通用场景；
• 0.8 ~ 1.0：高创意性，适合文案创作、脑洞内容，准确性下降。

3.3 stream 流式参数

• stream=false：一次性返回完整结果，适合后台批量处理、接口同步返回；
• stream=true：逐段分片返回，适合前端聊天页、实时展示场景，优化体验。

---

四、多模态能力（图片解析）

通义千问全系支持图片、文本混合输入，通过 Base64 编码传递本地图片：

import base64

def image_to_base64(image_path: str) -> str:
    """本地图片转base64链接，适配多模态接口"""
    with open(image_path, "rb") as img_file:
        encode_data = base64.b64encode(img_file.read()).decode("utf-8")
        return f"data:image/jpeg;base64,{encode_data}"

# 图文混合请求格式
messages_with_image = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "详细描述这张图片的内容"},
            {"type": "image_url", "image_url": {"url": image_to_base64("test.jpg")}}
        ]
    }
]

---

五、LangChain 高阶开发

5.1 核心概念释义

1. LangChain：大模型应用开发框架，封装记忆、工具、文档解析、链式调用，快速搭建复杂AI业务；
2. Agent 智能体：基于 LLM 自主思考、任务拆解、工具调用、闭环执行的运行模式，脱离固定问答；
3. 二者关系：LangChain 是开发工具底座，Agent 是基于框架实现的高级能力。

5.2 依赖安装

# 核心框架
pip install langchain
# OpenAI 协议集成
pip install langchain-openai
# 联网搜索工具
pip install tavily-python langchain-tavily
# 记忆持久化（LangGraph）
pip install langgraph

5.3 基础 Agent 自定义工具示例

通过装饰器快速注册工具，AI 自动判断是否调用对应能力：

from dotenv import load_dotenv
import os
from langchain_openai import ChatOpenAI
from langchain.tools import tool
from langchain.agents import create_agent
from langchain_core.messages import HumanMessage

load_dotenv()

# 初始化百炼大模型
llm = ChatOpenAI(
    api_key=os.getenv("ALIYUN_API_KEY"),
    base_url=os.getenv("ALIYUN_BASE_URL"),
    model=os.getenv("DEFAULT_MODEL"),
    temperature=0.1
)

# 自定义工具：方法注释为AI识别关键，必须清晰
@tool
def get_weather(city: str) -> str:
    """根据城市名称查询实时天气
    :param city: 城市中文名
    """
    return f"{city}：晴天 25℃，适宜出行"

@tool
def get_train_info(departure: str, destination: str) -> str:
    """查询两地直达高铁班次
    :param departure: 出发城市
    :param destination: 目的城市
    """
    return f"{departure}→{destination}，高铁G102 08:00发车"

# 注册工具列表
tools = [get_weather, get_train_info]
# 创建智能体
agent = create_agent(llm, tools)

# 执行复杂任务（自动调度多工具）
result = agent.invoke({
    "messages": [HumanMessage("帮我规划北京到上海2天旅行，查询天气和高铁")]
})
print("AI最终方案：\n", result["messages"][-1].content)

5.4 LangChain 标准消息对象

封装原生字典格式，代码更优雅、类型更安全：

LangChain 对象	对应原生 Role
SystemMessage	system
HumanMessage	user
AIMessage	assistant

使用示例：

import time
from langchain_openai import ChatOpenAI
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
from dotenv import load_dotenv
import os

load_dotenv()
llm = ChatOpenAI(
    api_key=os.getenv("ALIYUN_API_KEY"),
    base_url=os.getenv("ALIYUN_BASE_URL"),
    model=os.getenv("DEFAULT_MODEL")
)

# 面向对象写法
messages = [SystemMessage("你是技术文档编写助手")]
messages.append(HumanMessage("介绍Python环境变量配置"))

# 流式调用
stream = llm.stream(messages)
full_text = ""
for chunk in stream:
    full_text += chunk.content
    print(chunk.content, end="", flush=True)

# 自动追加会话
messages.append(AIMessage(full_text))

5.5 联网工具 Tavily 集成

专为大模型设计的实时搜索工具，替代自定义爬虫，快速获取实时信息：

1. 官网注册获取 TAVILY_API_KEY；
2. .env 新增配置：TAVILY_API_KEY=你的密钥；
3. 代码集成：

from tavily import TavilyClient
from dotenv import load_dotenv
import os

load_dotenv()
tavily = TavilyClient(api_key=os.getenv("TAVILY_API_KEY"))
# 实时联网搜索
resp = tavily.search("2026年4月武汉天气")
print(resp)

5.6 LangGraph 短期记忆（自动会话）

解决原生方案手动维护 messages 的痛点，通过 thread_id 隔离多用户会话，内置快照记忆：

from dotenv import load_dotenv
import os
import time
from langchain_openai import ChatOpenAI
from langchain_core.messages import SystemMessage, HumanMessage
from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver

load_dotenv()
# 初始化模型
llm = ChatOpenAI(
    api_key=os.getenv("ALIYUN_API_KEY"),
    base_url=os.getenv("ALIYUN_BASE_URL"),
    model=os.getenv("DEFAULT_MODEL"),
    temperature=0.7
)

# 绑定内存级记忆存储器
agent = create_agent(model=llm, tools=[], checkpointer=InMemorySaver())
# 会话唯一标识，区分不同用户
session_config = {"configurable": {"thread_id": "user_001"}}

# 首轮对话
first_msg = [SystemMessage("你是AI助手"), HumanMessage("自我介绍200字")]
print("AI（流式）：", end="", flush=True)
stream = agent.stream({"messages": first_msg}, config=session_config, stream_mode="values")

full_response = ""
for chunk in stream:
    latest_msg = chunk["messages"][-1]
    content = latest_msg.content or ""
    if content and content not in full_response:
        print(content[len(full_response):], end="", flush=True)
        full_response = content
print()

# 第二轮对话：无需传入历史，自动读取记忆
second_msg = [HumanMessage("我上一轮提问了什么？")]
resp = agent.invoke({"messages": second_msg}, config=session_config)
print("AI回复：", resp["messages"][-1].content)

扩展：生产环境可替换为数据库持久化存储器，实现会话长期保存。

---

六、工程化接入总结

1. 简单项目：优先使用 OpenAI 兼容模式，接入快、代码简洁；
2. 复杂业务：基于 LangChain + Agent 实现工具调用、任务拆解；
3. 多用户场景：使用 LangGraph 记忆组件，通过 thread_id 隔离会话；
4. 密钥安全：统一环境变量管理，禁止硬编码、禁止前端直接暴露密钥；
5. 选型建议：固定模型版本、合理配置 temperature、超时时间，保障服务稳定。

---