企业官网建设流程全解析

我像是给自己挖了坟墓——这是 AI 转型时期很多一线工作者说过的一句真实感慨。对技术人员来说，这种焦虑更多来自工作内容的变化：AI 编程助手能快速生成样板代码、写单元测试、解释陌生报错，大模型 API 开始承担客服、审核、数据分析等原本需要人反复处理的环节。问题已经不是要不要接受 AI，而是技术人员该用什么方式参与这场转型，让 AI 成为可被自己理解和控制的工程工具，而不是反过来替代自己。

这篇文章围绕一条完整的技术主线展开：先从机制上分析 AI 转型对技术工作的影响，然后搭好一套可用于学习和实验的开发环境，再从零实现一个最小可运行的 RAG 问答应用，把“文档加载、文本切分、向量检索、大模型生成”这条链路真正跑通，最后给出运行验证、效果评估、问题排查和长期学习路线。完成这个闭环后，你至少能从“会用 AI 工具”推进到“能做 AI 应用”，并在实际项目中具备独立排查问题的能力。

1. 先理解 AI 转型为什么让一线工作者焦虑

1.1 被替代的是任务，不一定是整个岗位

“我像是给自己挖了坟墓”这句话在一些场景里是成立的，但它描述的并不是“AI 取代了整个职业”，而是“一个人把自己长期固定在了一类可以被自动化的任务上”。

举个例子。一个后端开发者的日常工作可以拆成：理解需求、设计接口、编写增删改查代码、写单元测试、调试线上问题、做代码评审、配置部署。AI 编程工具目前最擅长的是中间这一段，也就是生成样板代码、补测试用例、解释报错信息。如果一个人每天的主要产出恰好集中在这类任务上，同时缺乏对业务的判断能力，那么 AI 对他的替代性确实很高。

反过来，如果一个开发者用 AI 快速完成样板代码，把节省下来的时间用于梳理业务边界、排查索引和事务问题、优化接口性能，他的位置就不容易被替代。被替代的不是岗位本身，而是岗位里那些可以标准化、模板化的部分。

1.2 技术人员的价值在向两侧迁移

从工程实践看，AI 转型后技术人员的价值正在向两端集中。

第一端是“定义问题”。包括把模糊的业务需求拆解成可执行的技术方案，明确评价标准，设计提示词和评估集，判断模型输出是否符合预期。第二端是“系统集成与兜底”。包括数据质量、权限控制、稳定性、成本、日志审计、回滚方案。中间层的机械编码工作正在被压缩。

这也就是为什么越来越多招聘要求里出现“AI 工程实践”“模型部署”“Agent 开发”这类关键词。模型本身是外部能力，技术人员的差异体现在能不能把模型安全、稳定、可评估地接入业务系统。

1.3 技术人员转型的四个常见方向

AI 转型不是只有“算法工程师”一条路，大多数后端、测试、运维、产品背景的人可以往四个方向走。

无论选择哪个方向，都需要一条共同的技术底座：环境搭建、模型调用、检索增强、部署运行、效果评估。下面从环境开始，把这套底座完整搭建起来。

2. 搭建一套能支撑学习和实验的 AI 开发环境

2.1 Python 与依赖环境

AI 生态里绝大多数框架、模型 SDK 和示例代码都优先支持 Python，学习阶段直接用 Python 可以避免很多兼容性问题。Java 团队可以关注 Spring AI，但在入门阶段，Python 的迭代速度更快，调试成本更低。

推荐使用 Python 3.10 或 3.11。隔离环境用虚拟环境完成，不要直接往系统 Python 里装依赖。

python --version python -m venv .venv source .venv/bin/activate pip install --upgrade pip

Windows 下激活命令是.venv\Scripts\activate。虚拟环境的作用是让项目之间的依赖互不干扰，尤其是 AI 框架更新很快，不同项目很可能需要不同版本的库。

项目先建立一个requirements.txt，内容可以按下面的参考版本锁定：

langchain==0.2.14 langchain-community==0.2.12 langchain-openai==0.1.23 langchain-text-splitters==0.2.4 chromadb==0.5.5 openai==1.40.3 python-dotenv==1.0.1

需要注意，LangChain 的 API 变化较快，新版本很可能调整方法名。上面的版本号只作为参考，落地前要结合自己的 Python 版本确认兼容性。

2.2 模型能力来源：API 与本地模型如何取舍

开发 AI 应用的第一步是确定模型从哪来。云模型 API 和本地部署模型各有利弊，不是越贵的方案越好。

入门阶段建议先使用云模型 API，把精力放在应用逻辑上。等到需要控制成本、满足数据合规要求时，再考虑用 Ollama 做本地实验，用 vLLM 这类推理框架做生产部署。

2.3 开发框架与日常 AI 编程工具

应用层框架的选择决定了代码组织方式。

LangChain 生态最全，文档加载、切分、向量存储、模型调用都有封装，但 API 变动频繁。Spring AI 适合 Java 团队，能够与 Spring Boot 项目自然整合。如果业务逻辑简单，也可以直接用模型厂商的 SDK，不引入额外框架。

日常开发中，Cursor、IDEA AI Assistant、VS Code Copilot 这类 AI 编程工具能显著加快编码速度。但要注意，工具会生成代码，却不会替你理解代码。使用 AI 编程工具时，每一步都要能解释清楚“它为什么这样写，边界条件是什么”。

如果之后要把服务发布出去，可以准备一台云主机。云主机按需购买即可，初期不需要高配，重点是学会把 Python 服务用 systemd、Docker 或反向代理跑起来。这些都是工程化必经环节。

3. 从零实现一个最小 RAG 问答应用

3.1 为什么第一个项目选择 RAG

RAG 全称是 Retrieval-Augmented Generation，检索增强生成。核心思路是：从私有文档库中检索出与问题相关的片段，再把这些片段作为上下文交给大模型生成答案。

选择 RAG 作为第一个项目有三个原因。第一，它解决的是真实问题：大模型训练数据是公开的，不知道企业内部文档内容，直接问会“一本正经地胡说八道”。第二，它覆盖了完整工程链路：数据清洗、文本切分、向量化、检索、模型生成、效果评估。第三，它是当前企业 AI 应用里落地最多的形态，做这个项目积累的经验可以平移到客服、内部知识库、文档问答等场景。

3.2 项目结构与数据准备

项目目录保持最小化，只保留必要文件。

rag_demo/ ├── .env ├── requirements.txt ├── data/ │ └── ops_manual.md └── rag_app.py

data/ops_manual.md是一份模拟的内部运维手册，内容要简单但能验证检索逻辑：

# 值班系统操作手册 ## 1. 登录说明 值班系统使用工号加动态口令登录。连续输错 5 次会锁定账号 30 分钟。 ## 2. 告警处理 收到磁盘使用率超过 85% 的告警时，先检查磁盘分布，再清理超过 90 天的日志文件。 ## 3. 数据备份 数据库每天凌晨 2 点执行全量备份，备份文件保留 14 天。

这样一份文档足以验证后续的三个核心能力：能否根据问题检索到正确片段，能否用检索片段生成答案，以及超出知识库范围时模型是否拒绝回答。

3.3 核心实现代码

rag_app.py包含两个部分：构建索引和回答问题。构建索引时读取文档、切分、向量化并写入 Chroma；回答问题时先检索相关片段，再交给大模型生成。

import os import sys from dotenv import load_dotenv from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.vectorstores import Chroma from langchain.prompts import ChatPromptTemplate load_dotenv() PERSIST_DIR = "./chroma_db" DOC_PATH = "./data/ops_manual.md" def build_index(): loader = TextLoader(DOC_PATH, encoding="utf-8") docs = loader.load() splitter = RecursiveCharacterTextSplitter( chunk_size=500, chunk_overlap=50, separators=["\n\n", "\n", "。", "！", "？", " "], ) chunks = splitter.split_documents(docs) embedding = OpenAIEmbeddings( model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-small") ) vectorstore = Chroma.from_documents( documents=chunks, embedding=embedding, persist_directory=PERSIST_DIR, ) vectorstore.persist() print(f"index built, chunks: {len(chunks)}") def ask(question: str): embedding = OpenAIEmbeddings( model=os.getenv("EMBEDDING_MODEL", "text-embedding-3-small") ) vectorstore = Chroma( persist_directory=PERSIST_DIR, embedding_function=embedding, ) retriever = vectorstore.as_retriever(search_kwargs={"k": 3}) context_docs = retriever.invoke(question) context = "\n\n".join([d.page_content for d in context_docs]) prompt = ChatPromptTemplate.from_messages([ ( "system", "你是企业内部知识库助手。只能根据上下文中已有的内容回答问题；" "如果上下文中没有答案，明确回答“知识库中未找到相关说明”，不要编造。", ), ("human", "上下文：\n{context}\n\n问题：{question}"), ]) llm = ChatOpenAI( model=os.getenv("LLM_MODEL", "gpt-4o-mini"), temperature=0.1, ) chain = prompt | llm answer = chain.invoke({"context": context, "question": question}).content return answer, context_docs if __name__ == "__main__": if len(sys.argv) > 1 and sys.argv[1] == "build": build_index() else: q = input("请输入问题：") answer, docs = ask(q) print("\n答案：") print(answer) print("\n检索来源：") for i, d in enumerate(docs, 1): print(f"{i}. {d.page_content[:80]}")

.env文件保存 API 配置，不要提交到代码仓库：

OPENAI_API_KEY=sk-xxxx OPENAI_BASE_URL=https://api.example.com/v1 LLM_MODEL=gpt-4o-mini EMBEDDING_MODEL=text-embedding-3-small

只要模型服务商提供 OpenAI 兼容接口，就可以通过OPENAI_BASE_URL切换到不同模型。使用国内模型时，把 base_url 和 model 名称改成对应的值即可。

3.4 启动与运行

pip install -r requirements.txt python rag_app.py build python rag_app.py

build会把文档切分并写入本地 Chroma 持久化目录。第二次运行问答时，不再需要重建索引，直接读取向量库即可。

输入“磁盘告警怎么处理”，预期输出会引用手册中的 85% 阈值和日志清理策略。如果改成“工资怎么计算”，模型应回答“知识库中未找到相关说明”，而不是自己编一个答案。

4. 关键机制与参数取舍详解

4.1 文档切分：检索质量的第一道门

文本切分决定了检索的基本单位。切分太大，一个块里塞进多个主题，检索时命中的内容可能包含大量无关信息；切分太小，单个块缺少上下文，模型无法理解完整语义。

代码里把 “。” “！” “？” 加进 separators，是为了让中文文本尽量在句子边界切断，避免一个完整句子被劈成两半。对于带标题的 Markdown 或结构化文档，生产环境需要按标题层级做父子块切分，而不是只按字符数硬切。

4.2 向量检索：语义匹配怎么做

切分完成后，每个文本块通过 Embedding 模型转换成向量。查询问题时，问题文本也被转换成向量，向量库用余弦相似度找到最接近的文本块。

search_kwargs={"k": 3}表示返回最相似的 3 个块。k 值太小，关键信息可能漏掉；k 值太大，不相关内容会混进上下文，影响生成质量。事实问答场景，3 到 5 是比较常用的区间。

向量检索适合语义匹配，但并不是所有检索场景都该用它。企业实践中，常见做法是“关键词检索 + 向量检索”的混合模式：先召回，再统一排序。对于编号、报错码、设备型号这类精确信息，关键词检索往往比向量检索更可靠。

4.3 生成阶段：提示词与生成参数

检索到上下文后，生成阶段是否可控，取决于提示词和采样参数。

系统提示词必须明确约束模型的行为。上面代码里的规则是“只能根据上下文回答，上下文没有就说不存在”。这是压制幻觉最基础的一层防护。

temperature控制生成的随机性。事实问答中建议设置在 0 到 0.3 之间，越大越容易发散，甚至编造内容。max_tokens控制输出长度，设置太小答案会被截断，太大则单次调用成本增加。

生产环境的提示词应单独管理，并针对不同业务场景写多个模板，不建议把提示词硬编码在业务代码里。

4.4 数据质量决定系统的上限

RAG 系统的质量上限由知识库文档决定。模型再强，也无法从错误、过时、重复的文档中生成正确答案。

使用知识库前要确认几点：文档是否有明确版本，是否有人负责更新；是否有重复或矛盾的说明；敏感信息是否做了权限分层；文档格式是否统一，能否稳定解析。很多 RAG 项目上线后发现效果不行，问题并不在模型，而在知识库本身。

5. 运行验证与效果评估

5.1 功能验证：三个必须测的场景

项目跑通不等于功能正确。最少要验证三个场景：

第一个是命中场景。问一个答案明确在文档里的问题，确认答案引用了正确内容，并且检索来源里出现了对应片段。

第二个是越界场景。问一个知识库不存在的敏感话题，确认模型拒绝回答，而不是把训练数据里的东西拿出来拼凑。

第三个是边界场景。问“账号被锁怎么办”，确认模型能回答出“输错 5 次、锁定 30 分钟”这两个关键约束。

示例输出：

答案： 收到磁盘使用率超过 85% 的告警时，先检查磁盘分布，再清理超过 90 天的日志文件。 检索来源： 1. 收到磁盘使用率超过 85% 的告警时，先检查磁盘分布，再清理...

验证时一定要把检索来源打印出来。如果答案对了但检索来源里没有对应内容，说明大模型可能在凭记忆作答，这是另一种形式的幻觉。

5.2 效果评估：不要只凭感觉

评估需要一套固定的测试问题集。从知识库中整理 20 到 50 个问答对，覆盖正常问题、边界问题、越界问题，然后建立三个简单指标。

上下文命中率衡量检索阶段是否把正确答案片段带回来了。答案正确率衡量最终回答是否准确。幻觉率衡量回答中有多少信息不在检索上下文里。每次修改切分参数、提示词或模型后，都用同一套问题集重跑，对比指标变化。这样就不需要靠“感觉好像变好了”来决策。

自动化评估可以借助 RAGAS、DeepEval 这类开源框架，也可以先用表格手工记录结果。对个人项目来说，先建立一套固定问题集，比盲目引入评估框架更有价值。

5.3 学习环境与生产环境的差异

个人电脑上能跑通的脚本，距离生产服务还有一段工程距离。

生产环境的 RAG 服务，除了写业务代码，还需要考虑知识库如何增量更新、检索接口如何限流、敏感文档如何控制权限、模型调用如何监控成本。这些内容越早接触越好。

6. 常见问题排查路径

6.1 依赖冲突与框架版本变化

现象：pip install报错，运行时出现 pydantic 兼容问题，或者 LangChain 某个类找不到。

原因：LangChain 等 AI 框架迭代快，版本之间 API 变动很大，Python 生态中 pydantic 版本冲突也非常常见。

检查方式：查看完整报错堆栈，用pip list确认当前环境中的版本，到框架官方变更日志里确认方法名是否调整。

处理建议：创建独立虚拟环境，按参考版本锁定依赖，升级框架时先跑一遍测试问题集。不要把项目直接安装在系统 Python 里。

6.2 检索结果为空或答非所问

现象：文档里明明有答案，模型却说找不到；或者返回的内容和问题完全无关。

原因：文本切分粒度不合理，中文标点没有加入分隔符；Embedding 模型不匹配；文档实际没被加载；旧的向量索引没有随文档更新。

检查方式：先打印构建索引时的chunks数量，确认文档确实被切分；再打印检索返回的片段，确认检索阶段是否命中；最后检查向量库持久化目录是否对应最新数据。

处理建议：调整chunk_size到 300 到 800 之间，加入中文分隔符；修改文档后必须重新执行python rag_app.py build重建索引。排查顺序是“数据有没有进来 -> 切片是否合理 -> 检索是否命中 -> 再考虑生成”。

6.3 API 超时、限流与费用问题

现象：请求等待很久后报超时，返回 429 限流错误，月底发现模型调用费用超出预期。

原因：没有设置重试和超时，并发调用过高，相同问题重复请求，没有做缓存，也没有预算告警。

检查方式：查看接口返回的 HTTP 状态码和错误体，到服务商控制台查看 token 用量和调用次数，结合日志确认哪些接口消耗最大。

处理建议：调用模型 SDK 时启用指数退避重试；对相似问题做缓存，减少重复调用；在服务商控制台设置每月预算告警；控制max_tokens，避免生成超长无效内容。

6.4 幻觉问题

现象：模型给出的内容在知识库中完全不存在，或者把多个文档的内容拼接成错误结论。

原因：检索阶段没有带回关键内容，模型只能凭训练记忆作答；系统提示词约束不够；temperature设置过高。

检查方式：打印context_docs，确认生成答案依据的上下文是否包含正确信息。如果上下文里根本没有该信息，问题在检索；如果上下文有信息但答案仍然错误，问题在提示词或生成参数。

处理建议：强化系统提示词，明确要求只能依据上下文回答，并要求模型引用来源片段；把temperature调到 0.1 或更低；用固定问题集记录幻觉率，每次改动后对比。

7. 面向长期转型的实践建议与学习路线

7.1 每周可执行的转型清单

转型不是学完一门课就完成的，建议把它拆成每周可执行的动作。

每周用模型 API 实现一个可运行的小功能，比如文档摘要、文本分类、关键词抽取。选一个开源 RAG 或 Agent 项目，读一条完整调用链，弄清楚数据从进入到生成经历了哪些步骤。记录每次提示词和参数变化后的效果差异，逐渐建立自己的评估问题集。学习 Docker 和云主机部署，把自己写的服务发布出去，再补上日志和监控。每次调用记录 token 消耗，建立成本意识。每季度复盘一次：你的工作中哪些任务已经被 AI 自动化，你在这些任务上的附加价值到底在哪里。

7.2 五个阶段的学习路线

第一阶段是模型 API 基础。掌握 chat、completion、embedding 三种核心接口的区别，理解 token 的含义和计费方式。

第二阶段是提示词工程。掌握 system prompt、few-shot、输出格式约束，知道哪些问题该调提示词，哪些问题该改流程。

第三阶段是 RAG 工程。沿本文的例子继续深入，学习文档结构解析、父子切分、混合检索、重排序。

第四阶段是 Agent 基础。学习 function calling、工具调用、任务拆解，了解 LangChain Agent 和 Spring AI 的实现差异。

第五阶段是部署与质量。学习 Docker、vLLM、监控告警，掌握评测集、成本控制、权限管理。这五个阶段对应了文首说的“AI 工程实践”和“AI 模型部署”这两类核心能力。

7.3 三个容易踩的坑

第一个坑是只复制不验证。网上代码片段可能来自不同版本，直接复制大概率报错。每段代码都要运行、理解、测试边界条件，才能变成自己的工程能力。

第二个坑是用 AI 加速但放弃理解。一直让 AI 生成代码却不阅读，时间一长，系统出了问题无法定位，需求变化无法评估影响。这正是“给自己挖坟墓”的技术版本：你不是被 AI 替代的，是被只会复制粘贴的自己替代的。

第三个坑是跳过评估直接上线。没有固定问题集，没有指标基线，任何修改都靠“看起来不错”来判断。结果就是系统越改越不可控。先建评估，再做迭代，这是 RAG 项目最值得投入的一步。

回到开头那句感慨。AI 转型期真正危险的不是模型变得更强，而是技术人员把自己的工作停留在“可以被自动化的任务层”。如果你能理解 RAG 链路里每一步为什么存在，能定位一次错误是来自切分、检索、提示词还是模型调用，能在数据质量、成本、权限这些工程问题上做出判断，你的位置就不是模型能轻易替代的。先跑通最小闭环，再迭代评估，这是 AI 转型里最有价值的第一步。