企业官网建设流程全解析

上个月，我把公司内部一个用了两年的关键词检索问答机器人，整个换成了DeepSeek驱动的智能问答对话系统。换完以后的最大感受有点出乎意料：模型能力其实只占三成，真正吃掉时间的，是对话系统外层那一圈设计——会话怎么管、工具怎么调、接入渠道怎么兼容、部署参数怎么调。这篇就把从零搭这样一个系统的完整过程写出来，包含API接入和本地部署的选型逻辑、多轮对话与工具调用的实现细节、如何接进VS Code和企业微信这类日常工具，以及我在vLLM和Jetson Orin上部署时踩过的性能坑。想给团队做内部知识库、客服机器人，或者一个能自己把事办了的私有助手的开发者，可以直接照着走一遍。

1. 动手前的需求拆解：问答系统到底要解决什么问题

很多人一上来就问“DeepSeek怎么接”，但真正卡住项目的往往不是API，而是“不知道自己要做一个多复杂的东西”。我先说句实在话：一次精心设计的prompt调用，和一套能稳定支撑业务的多轮对话系统，中间隔着一条河。动手之前，建议花半小时把下面几个问题想清楚，能省下后面一大半返工时间。

1.1 先分清你做的到底是哪种“问答”

同样是智能问答，形态不同，工程复杂度完全不同。我习惯分成三类：

• FAQ式单轮问答：用户问一句，模型答一句，不需要记住前面聊过什么。适合官网常见问题、产品说明，成本最低，用一段system提示词限定回答范围就行。
• 多轮会话助手：模型需要记得用户上一轮提到的条件。比如用户说“帮我挑一台适合做数据分析的笔记本”，下一轮又补一句“预算提高到八千”，模型必须知道“八千”指的是笔记本预算，而不是其他东西。这就要管理会话状态。
• 任务型智能体：不只“说”，还要“做”。用户问“帮我查一下订单JD20240001到哪了”，系统得真正去调库存接口或订单系统，拿到数据再回答；用户说“总结一下这周的工单”，系统得去查工单列表。这个形态就必须引入工具调用（function calling），复杂度直接跳一个台阶。

你自己的场景属于哪一类？如果只是静态知识问答，不建议一上来就上全套智能体框架。先做FAQ式，跑通了再往多轮和工具方向加，是投入产出比最高的路径。

1.2 数据边界和交互入口也要提前定

模型本身不知道你公司内部的事。问答系统的核心价值，一半来自你将什么样的数据喂给它。想清楚三个问题：

• 数据在哪：知识文档是静态文件，还是在数据库里？需不需要实时读取？比如客服机器人查物流，数据每分钟都在变，这就要设计检索或接口查询链路。
• 可信度要求：内部知识参考，模型自由发挥问题不大；但一旦涉及价格、法务、医嘱这类高风险回答，必须要求模型引用来源，甚至做“答不上来就明确说不知道”的约束。
• 用户从哪进来：微信、企业微信、网页挂件、命令行终端，渠道决定了接入层怎么写。企业微信要考虑员工身份，网页挂件要考虑匿名访问，终端工具则要考虑交互格式。

这些边界不确定清楚，后面每写一段代码都可能是白写。

1.3 用一张表把需求换算成技术选型

我通常会把需求拆成一张对照表再决定选型，比如：

这张表不复杂，但能逼你把自己的核心诉求写清楚。我当时就是因为把“内部多轮助手”和“数据不出园区”两个需求都列上了，才决定做本地部署为主、API备用，后面所有技术选型都有了依据。

2. 模型接入的两种主流方式：API调用与本地部署

接入DeepSeek有两条主路：走官方API，或者自己部署开源权重。两条路我都跑过，各有各的坑和甜头。这里把两条路的实操步骤都写一遍，顺便说说怎么根据成本选型。

2.1 走API：十来行代码跑通第一轮对话

DeepSeek的API兼容OpenAI的接口协议，所以直接用openai的Python SDK就能调，不需要单独封装一套客户端。最开始的“deepseek api如何调用”这个问题，答案其实就是“把它当成一个改过base_url的OpenAI兼容服务”。

import os from openai import OpenAI client = OpenAI( api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com" ) resp = client.chat.completions.create( model="deepseek-chat", messages=[ {"role": "system", "content": "你是一个严谨的智能问答助手，回答简洁准确。"}, {"role": "user", "content": "你好，介绍一下你自己"} ], temperature=0.7, max_tokens=1024, stream=False ) print(resp.choices[0].message.content)

这里有几个容易忽略的细节：

• API Key放在环境变量里，别硬编码进代码，更别推到Git仓库。一个把key提交到公开仓库的教训，通常发生在每个团队里至少一次。
• base_url不要拼错。以官方开放平台文档为准，别把/v1这种路径凭记忆乱加，拼错的结果是请求能通但路由飘了，报错还不好猜。
• model字段用什么。官方API常见的对话模型名是deepseek-chat，推理增强模型是deepseek-reasoner，具体以你账号可见的模型列表为准。先用chat模型把链路跑通，需要推理增强再切。
• temperature按场景调。知识问答建议0.3以下，减少编造；创意写作或头脑风暴可以调高到0.8以上。

2.2 本地部署：数据可控但没那么“免费”

本地部署DeepSeek开源权重，最常用的服务框架是vLLM，它对高并发吞吐优化得很好。基础命令长这样：

vllm serve deepseek-ai/DeepSeek-R1-Distill-Qwen-7B \ --max-model-len 8192 \ --gpu-memory-utilization 0.9

跑通之后vLLM会暴露一个OpenAI兼容的接口，地址通常是http://localhost:8000/v1，你拿上面那套OpenAI客户端代码，把base_url换成这个地址就能用。

但这个方案有几个真实成本，别被“免费开源”四个字骗了：

• 显存是硬约束。7B左右的模型加8192上下文，至少需要一张16G以上的卡；更大规模的模型，显存需求会到50G以上。显存不够，就得用4bit或8bit量化，一是占用少，二是会有精度损失。
• 本地部署不等于零成本。电费、机柜、显卡折旧，长期跑下来未必比API便宜，尤其在并发低、调用量小的时候，API按量付费反而是更明智的选择。
• 运维责任全在自己身上。API服务挂了你只需要看状态页；本地部署挂了你需要自己排查，从驱动版本、CUDA环境一直查到vLLM参数配置。

如果你有明确的数据合规要求，比如“对话内容绝不能出园区”，那本地部署是唯一答案。否则，API先用起来，会让你的项目推进速度快得多。

2.3 成本不是一个数字，而是一套策略

DeepSeek的计费结构是典型的token计费：输入和输出分开算，缓存命中的输入价格通常更便宜。具体单价以官网计费页为准，但成本控制的思路是通用的。

我算过一笔账：假设系统一天处理1万轮问答，平均每轮输入1000 token（包含历史上下文）、输出300 token。按一个常见价目粗算，输入加输出一天的token费用是可预期的，拉通一个月能看到一个明确的数字。这个数字会逼你开始考虑三件事：

• 控制上下文长度。多轮对话很容易把1000 token的输入滚成5000 token，费用按线性增长。解决办法是限制历史轮数，或对旧消息做滚动摘要。
• 把重复问题拦在前面。员工经常问“零食报销流程是什么”，这类问题第一次回答后就可以缓存结果，下次直接返回，不消耗模型调用。
• 简单问题走小模型，复杂问题走大模型。先用规则或分类模型判断问题难度，简单FAQ直接给固定答案，只有疑难问题才调用DeepSeek。这种“分级路由”一年能省下40%以上的token费。

3. 核心问答链路的关键实现：从“能聊”到“好用”

把API跑通只是起点。一个能稳定工作的问答系统，核心有四块：会话状态管理、提示词设计、工具调用、外部知识接入。每一块都决定系统是“玩具demo”还是“生产工具”。

3.1 会话状态管理：别把历史一股脑全塞给模型

DeepSeek是纯无状态的，你每次调用都把完整上下文放在messages里。所以会话管理本质上是你自己维护一个消息数组。基本结构是：

messages = [ {"role": "system", "content": "你是一个企业知识问答助手..."}, {"role": "user", "content": "差旅报销的额度是多少？"}, {"role": "assistant", "content": "根据制度，普通员工单次差旅报销上限是3000元。"}, {"role": "user", "content": "如果是总监呢？"} ]

这个数组会越来越长，而模型有上下文窗口上限。中文场景下，一个汉字大约对应1到1.5个token，你可以用官方tokenizer做精确估算，但在动手阶段用“1000 token约等于600到900汉字”这个粗略换算就够用。

我的做法是设定一个max_history_token（比如2000），在每次请求前检查消息数组的总token数，超出后从最早的对话消息开始丢弃，system消息永远保留。如果业务确实需要长对话记忆，可以再做一层“滚动摘要”：让模型把前面20轮内容总结成一段要点，替换掉原始历史。这一步能让对话质量稳定很多，也直接影响账单数字。

3.2 提示词设计决定边界和风格

同一个模型，prompt不同，输出的专业度天差地别。适合问答系统的system提示词模板，我会这样写：

你是企业内部智能问答助手，名称叫“小答”。 回答原则： 1. 只能依据提供的知识内容回答，不编造。 2. 如果知识范围里没有答案，明确回答“未找到相关信息，请补充资料或转人工”。 3. 回答简洁，控制在200字以内，使用项目符号列出要点。 4. 涉及金额、日期、操作步骤时，必须引用原文片段。

这套提示词的重点不是“夸模型”，而是把回答边界焊死。接知识库的问答系统最怕模型自由发挥，尤其涉及制度、数据、金钱的时候，一句“仅供参考”式的话术对生产系统毫无意义。

需要结构化输出时，比如让模型从用户问题里抽取参数，我会在prompt里要求：

请从用户消息中抽取查询条件，只输出JSON，格式为 {"intent": "query_order", "order_id": "..."} 不要输出任何解释文字。

然后解析JSON时做个兜底：先去掉可能的markdown代码块标记（json和``````），再解析。模型偶尔会在输出外面包一层代码块，这个现象很常见，别被坑到。

3.3 工具调用：让问答系统真的能“办事”

静态知识问答做到这一步已经能用了，但距离“智能对话系统”还差关键一环——工具调用。用户问“帮我看看工单T20240088的状态”，模型自己不知道工单状态，它需要去调你的工单系统。

DeepSeek API支持function calling。你定义工具schema时，它会像下面这样描述：

{ "type": "function", "function": { "name": "get_ticket_status", "description": "查询工单当前状态", "parameters": { "type": "object", "properties": { "ticket_id": {"type": "string", "description": "工单编号"} }, "required": ["ticket_id"] } } }

把tools参数传给接口后，模型如果判断需要查询，会返回tool_calls，而不是直接写答案。真实系统的完整调用循环是：

while True: resp = client.chat.completions.create( model="deepseek-chat", messages=messages, tools=tools ) msg = resp.choices[0].message messages.append(msg) # 没有工具调用，直接返回最终答案 if not msg.tool_calls: break # 逐个执行工具，把结果以tool角色回传 for tc in msg.tool_calls: result = execute_tool(tc.function.name, tc.function.arguments) messages.append({ "role": "tool", "tool_call_id": tc.id, "content": json.dumps(result, ensure_ascii=False) })

一定要把这个循环写对。模型返回tool_calls之后，你必须执行工具并把结果回传，再次调用API，直到模型不再要求调用工具。很多新手在这里漏掉“结果回传”这一步，导致对话直接断掉，或者出现后面要讲到的一个典型报错。

工具调用还有一个简化变体，适合中小规模知识库：不搞向量检索库，直接把FAQ压缩进上下文。比如把100条常见问答按主题分组，在用户提问时先用关键词把相关条目选出来，拼接成“知识片段”放到system消息里。这个方案在几百条知识的规模下效果不错，架构简单，也好调试。等知识规模涨到几千条以上，再去上真正的向量检索（RAG），这也是我后来的经验。

4. 把问答系统搬进日常工具链

模型链路通了，接下来要解决的是“人在哪里用”。我实际接过的渠道包括编码工具、企业微信、微信公众号和多种智能体框架，每一个渠道都有自己的脾性。

4.1 VS Code和Codex里把DeepSeek当副驾

开发团队最常用的接入方式是让DeepSeek进入编码流程。做法不难：在Codex或其他编码助手工具的配置里，把模型服务地址指向DeepSeek的兼容接口，填好API Key和模型名，就能在编辑器里直接对话、生成代码。

需要注意两点：

• 并发限制。团队共用同一个API Key时，突发并发很容易触发限流。我踩过这个坑：早上十点全组一起问代码问题，系统直接报限流错误。解决办法是加一层队列或限速，把请求摊平；更稳的是走企业级账号，拿到独立的配额。
• 上下文长度。编码会话中粘贴大段代码会让token消耗飙升。我会在团队规范里写清楚“贴代码前先精简，只保留相关函数”，把成本降下来，模型注意力也更集中。

接入VS Code或Codex这类工具的好处是能集中管理计费和审计。每个人的提问都会经过同一个服务端，日志留痕，哪段代码是AI生成的都能追溯，这在团队协作里很实用。

4.2 企业微信和公众号的接入差异

对外公众号和对内企业微信，接入逻辑完全不同。我做了张对比表：

实现上，我用FastAPI搭了一层回调服务，接收IM平台推送的消息，校验签名，把消息转发给问答服务，再把回复结果返回。公众号有过那个经典坑：被动回复必须在5秒内完成。模型思考加网络传输很容易超5秒，一超时微信就重试，用户会看到两次回复甚至错乱回复。

我的解法是“先占位，后异步下发”：收到用户消息后立即响应“正在思考中”，把真实结果放到异步任务里生成，生成完用客服消息接口主动推给用户。企业微信则没有这个问题，应用消息直接用主动发送接口推就行，内部员工体验更好。

4.3 多智能体编排：从单个模型到“一个团队”

单条问答链路跑顺之后，我开始折腾社区里的多智能体编排工具，也就是热词里常说的DeepSeek Harness这类东西。它的核心思路是：不再让一个模型串完所有事，而是把任务拆给多个专门化智能体，比如意图识别agent负责判断用户想干嘛，检索agent负责找资料，回答agent负责生成最终话术。一个负责“管”，几个负责“做”，能力边界清晰很多。

这类工具的另一个亮点是skill机制。你可以把一些解决过的具体问题沉淀成可复用的指令卡，比如“查询员工社保时先确认员工所在城市”这样带业务规则的小经验。下次相关对话触发时，agent会把对应skill加载进来，行为更稳定。我也试过配合Playwright做浏览器自动化，让agent自己去内网页面取数。场景是替运维同事自动查某台设备的监控页面——agent学会“打开页面，登录，定位指标，截图”，非常有复现价值。

但我必须给一句忠告：这类编排框架的版本升级非常容易破坏你调好的流程。我就经历过“升级一个小版本后，所有工具的解析规则全变了，对话行为一步错步步错”的情况，最后只能翻文档找旧版配置回滚。生产环境一定要锁版本号，升级前先对配置和prompt做快照。网上搜“harness怎么退回到v0.1.5-rc.2”这个问题的人越来越多，从侧面说明这不是我一个人踩过的坑。

5. 部署参数与性能调优实测

如果你选择本地部署，性能调优就是每天都要面对的课题。我把我实际测过的关键参数和调试思路完整过一遍，这些经验在vLLM和Jetson Orin上都有。

5.1 vLLM参数对吞吐的影响

vLLM的几个启动参数直接决定了你服务的吞吐量和稳定性：

• --max-model-len：上下文最大长度。开得越大，能处理的对话越长，但KV Cache占的显存越多，并发能力下降。我看到很多人一上来就照着官方最大值开，结果显存OOM。实际项目里先按你的业务场景定，比如内部会话历史控制在2000 token，那8192已经非常充裕。
• --gpu-memory-utilization：控制显存利用率。设0.9意味着留10%给其他模块，避免OOM崩溃。设0.99看上去最大化利用了显存，但一旦有其他进程抢显存就很容易崩。我稳定在0.9左右。
• 开启前缀缓存：如果多个请求带同样的system提示词，前缀缓存能显著降低首字延迟。在vLLM里对应的是启用prompt cache相关的参数，具体以当前版本文档为准。
• 连续迭代批次：vLLM会把并发请求拼进同一个batch，吞吐利用率大幅提升。实际测下来，并发10个请求时，开vLLM比逐条请求要好一个量级。

配置完记得做一次压测，别只测单条延迟。拿脚本并发打20个请求，看P95延迟和是否OOM，这比我当初“单条聊着挺快就直接上线”的判断可靠得多。

5.2 首字延迟是体验的第一道门槛

聊天体验的瓶颈往往不是整体生成速度，而是“第一句话多久出来”。在本地部署中，TTFT（首字延迟）受到请求排队、prompt处理、显存状态多重影响。我这边测下来的经验是：

• 流式输出必须开。stream=True时，模型边生成边吐字，用户约1秒内就能看到内容开始滚动；如果不开流式，用户要等全部答案生成完，长回答可能要等十几秒，体验完全是两回事。
• 前端配合打字机效果。后端流式返回，前端逐字追加，用户以为系统“边想边打”，心理等待时间会大幅缩短。
• 分诊降级。简单问题，比如“今天放假吗”，在应用层直接匹配规则回答，根本不需要走到模型层。只有复杂问题才进大模型。这一步不只是省token，更是把高频低价值请求从模型链路里摘出去，让真正复杂的请求得到更充裕的计算资源。

5.3 边缘设备Jetson Orin上部署的取舍

因为一块业务要求“断网也要能答”，我在Jetson Orin上跑过本地部署，算是一次很实在的边缘设备实测。Orin这类设备自带GPU，但显存和带宽远不能跟服务器显卡比。我的结论是：

• 能跑，但规模要克制。7B级别以下、经过4bit或8bit量化的模型可以流畅对话；再大的模型会很吃力，慢到用户没法忍。
• 并发能力极弱。单路对话没问题，多路并发请求一上来，排队时间和首字延迟会明显恶化。这种设备更适合“固定工位，一人一台内部查询终端”的场景，不适合对外开放。
• 最大的红利是数据不出设备。所有推理都在盒子里完成，没有数据离开设备的合规负担。这一点对医疗、涉密、研发代码审查这类场景非常关键。

如果你也想在Orin上做，建议先量化模型，再把vLLM或对应推理框架跑通，最后用一段小的并发脚本测出真实的业务容量上限。别只看“模型能回答”，就以为它能扛住生产流量。

6. 踩坑记录：三个让我加班到深夜的现场

最后写几个真实踩坑的完整排查过程。这些坑不一定每个你都会遇到，但排查思路是通用的，尤其是“先把范围缩小到模型还是链路”这件事，能让你少走太多弯路。

6.1 排查“request extension preparation failed”

这个报错我第一次看到是在接入自己的服务框架时，连API Key都没问题，但请求就是发不出去。完整排查链路我记成三步走：

1. 先用最原始的curl绕过所有代码，只测API连通性。如果curl正常，问题基本锁定在你的代码封装或SDK版本上；如果curl都报错，先去检查网络、域名和Key。这一步能把问题范围砍掉一半。
2. 检查请求体大小。当我把超长历史一股脑塞进messages后，请求体超过服务端限制就触发这个报错。把历史截断到合理长度后，问题消失。
3. 检查本地部署时的模型上下文长度。如果是自己起的vLLM服务，请求里的输入token数超过--max-model-len，也会出现类似拒答。把服务的上下文参数调大，或者限制请求历史长度。

日志方面有个非常具体的建议：不要在日志里直接打印API Key或完整请求头。排查问题时用“Key前六位+后四位”的方式打码输出，既够定位，又安全。

6.2 解决“messages tool calls need immediate results”

这个报错的经典场景是：智能体框架收到了模型返回的tool_calls，但没有立刻把工具执行结果回传，就做了下一次对话请求。模型视角下，“你让我查用户说的工单，却连查没查都不告诉我，我当然只能报错”。

所以正确的工具调用循环，就是我在第3.3节写的那段代码：识别tool_calls、执行函数、把结果用role为tool的消息追加回去，再继续请求。确保每一条tool_calls都有对应的tool结果消息，且tool_call_id对得上，否则模型也会认为消息链条断裂。

这个报错的价值在于，它会逼你把“调用-执行-回传”的闭环写完整。我第一次遇到时以为是模型版本问题，调试半天才发现是我自己的循环少写了一段。

6.3 治“模型聊着聊着变笨了”的多轮退化

系统上线一段时间后，我收到反馈：用户在多轮对话的最后，模型开始答非所问，甚至忘掉用户最开始问的问题。排查后发现两个原因：

• 历史消息过多，把关键信息挤出了注意力窗口。系统把20轮对话全部塞进上下文，模型越往后越抓不住重点。修复方式是加滚动摘要，把旧对话提炼成要点，只保留最近几轮的原始消息。
• 一次会话里混入了过多话题。用户把不相关的问题在同一个会话里连续提问，模型很难切换状态。解决办法是给会话加主题识别，检测到话题突变时主动开启新一轮会话，而不是无限延续旧上下文。

这里还有一个合规和稳定性层面的心得：总有些用户会尝试用特殊构造的指令让模型说一些它不该说的内容。开发者的正确做法不是研究怎么对抗，而是按平台的规范设计提示词，在应用层做输入校验和敏感内容过滤，必要时加人工复核流程。这不只是技术选择，更是让系统能长期稳定运转的底线。一个对话系统的边界清晰、反馈明确，用户的信任度反而更高——这比任何“越狱”式的临时取巧都重要得多。

真要说这个项目留下的最大经验，就是：模型只是内核，体验上限来自外围设计。先按最简单的链路跑通第一轮问答，再一步步加上历史管理、工具调用、渠道接入；每一次改动都要把日志和可观测性做进去，否则出问题时你根本分不清是模型抽风还是链路出错。下一步我准备把知识库的召回质量再提一档，把回答的引用来源做扎实，让业务方真的敢拿它直接回答客户。你若也正在搭同样的系统，希望这篇能帮你把该踩的坑提前绕开。