目录

一、写作缘起

二、环境准备：把钥匙藏进 .env

三、裸调 API：用最简代码验证链路

四、LangChain 抽象：为什么需要再包一层

五、从单轮到多轮：Memory 的引入

六、总结与展望

---

一、写作缘起

        我在最近的一次原型迭代中，需要把阿里灵积（DashScope）平台上的通义千问大模型接入到 LangChain 框架，以便在后续产品中同时支持用户端问答与管理端批量分析。为了让后来者少走同样的弯路，我决定把踩坑与经验整理成一篇面向 CSDN 的技术长文。全文约五千字，力求把“API 直接调用”与“LangChain 集成”之间的思维跃迁讲透。文中所有代码均已在 Python 3.12 与 LangChain 0.3 社区版上通过测试，读者可放心复现。

二、环境准备：把钥匙藏进 .env

        任何一次云端调用都要先解决凭证管理。我采用最朴素的 dotenv 方案：在项目根目录新建 .env 文件，把阿里云的 AK 写进去。

import os
from dotenv import load_dotenv
load_dotenv(override=True)

DASHSCOPE_API_KEY = os.getenv("ALIYUN_API_KEY")
print(DASHSCOPE_API_KEY)

这段脚本只有四行，却完成了三件小事：

1. 把 .env 文件中的键值对加载到进程环境变量；

2. 通过 override=True 强制覆盖同名环境变量，防止 CI 系统里出现“幽灵”AK；

3. 打印一次确认，确保密钥读入无误。

注意：千万不要把 .env 提交到 Git，也不要把密钥硬编码。

三、裸调 API：用最简代码验证链路

        在引入任何框架之前，我习惯先“裸跑”一次 API，以排除网络与权限问题。官方兼容 OpenAI 格式，因此我选择 OpenAI 官方 SDK 作为最轻量的探针。

from openai import OpenAI

client = OpenAI(
    api_key=DASHSCOPE_API_KEY,
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
)

response = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {"role": "system", "content": "你是乐于助人的助手，请根据用户的问题给出回答"},
        {"role": "user", "content": "介绍一下你自己。"},
    ],
)

print(response.choices[0].message.content)
print(response.model_dump_json())

这里有三处细节值得展开：

1. base_url 覆盖了默认的 OpenAI 域名，使 SDK 把请求转到阿里灵积。

2. model 字段填写的是平台侧定义的模型名称 "qwen-plus"，而非 "gpt-3.5-turbo"。

3. model_dump_json() 可以一次性打印原始 JSON，方便调试时查看 usage、id 等元数据。

 运行结果：

嗨！我是Qwen，是阿里云研发的一款超大规模语言模型。我可以帮助你回答问题、创作文字，比如写故事、写公文、写邮件、写剧本、逻辑推理、编程等等，还能表达观点，玩游戏。我支持多种语言，包括但不限于中文、英文、德语、法语、西班牙语等。如果你有任何问题或需要帮助，随时告诉我，我会尽力提供支持！
{"id":"chatcmpl-7d50dc00-c40e-9956-a35e-4743d669d823","choices":[{"finish_reason":"stop","index":0,"logprobs":null,"message":{"content":"嗨！我是Qwen，是阿里云研发的一款超大规模语言模型。我可以帮助你回答问题、创作文字，比如写故事、写公文、写邮件、写剧本、逻辑推理、编程等等，还能表达观点，玩游戏。我支持多种语言，包括但不限于中文、英文、德语、法语、西班牙语等。如果你有任何问题或需要帮助，随时告诉我，我会尽力提供支持！","refusal":null,"role":"assistant","annotations":null,"audio":null,"function_call":null,"tool_calls":null}}],"created":1754141220,"model":"qwen-plus","object":"chat.completion","service_tier":null,"system_fingerprint":null,"usage":{"completion_tokens":87,"prompt_tokens":32,"total_tokens":119,"completion_tokens_details":null,"prompt_tokens_details":{"audio_tokens":null,"cached_tokens":0}}}

四、LangChain 抽象：为什么需要再包一层

        裸调 API 适合单次问答，但产品里往往要管理对话历史、构建链式调用、接入检索增强（RAG），甚至把模型输出绑定为结构化对象。LangChain 的价值就在于把这些横切关注点抽象成“链（Chain）”、“记忆（Memory）”、“提示模板（PromptTemplate）”等可重用组件。

        如果把裸 API 比作裸机汇编，LangChain 就是操作系统：它让你用高级语言写业务逻辑，而不必关心寄存器分配。下面我给出最小可运行的 LangChain 接入示例。

from langchain_community.chat_models.tongyi import ChatTongyi

model = ChatTongyi(dashscope_api_key=DASHSCOPE_API_KEY)

question = "一句话介绍佛山大学"
result = model.invoke(question)
print(result.content)

对比代码块2，你会发现代码量骤减：

• 不再需要手写 messages 数组；

• 不用处理 OpenAI SDK 的 response.choices[0]；

• LangChain 把字符串自动封装成 HumanMessage，把模型输出封装成 AIMessage。

ChatTongyi 是社区贡献的适配器，内部继承自 BaseChatModel，因此具备 LangChain 生态的一切能力，比如流式输出、异步调用、批处理等。

运行结果：

佛山大学是一所位于中国广东省佛山市的综合性大学，致力于培养应用型人才，学科涵盖工、理、管、文、法、教育等多个领域。

五、从单轮到多轮：Memory 的引入

        用户端聊天最核心的问题是“记住上下文”。LangChain 提供 ConversationBufferMemory，只需三行代码即可接入：

from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain

memory = ConversationBufferMemory()
chat_chain = ConversationChain(llm=model, memory=memory, verbose=True)

reply1 = chat_chain.predict(input="佛山大学在哪座城市？")
reply2 = chat_chain.predict(input="它的简称是什么？")

        第二句提问中并没有出现“佛山大学”，但模型依然能回答“简称佛大”，因为 Memory 已把第一轮对话自动注入 prompt。

六、总结与展望

        本文从一次最小可运行的 API 调用出发，逐步引入 LangChain 的抽象层。读者只要按图索骥，即可在一小时内把通义千问接入 LangChain，并在一天内把模型正式纳入 LangChain 生态实现一句式问答。下一步，我计划继续深入去探讨 RAG、结构化输出、流式异步、异常重试等真实场景，实现真正的“Agent 级”产品。届时我会再写一篇姊妹篇，敬请期待。