#如何使用 LangChain 构建 RAG

import { ChatOpenAI } from '@langchain/openai'

export const model = new ChatOpenAI({
  // 模型名称
  model: 'deepseek-v4-flash',
  // 控制生成内容的随机性
  temperature: 0,
  // 模型服务的 API Key
  apiKey: process.env.DEEPSEEK_API_KEY,
  // OpenAI 客户端的连接配置
  configuration: {
    // OpenAI 兼容接口地址
    baseURL: 'https://api.deepseek.com',
  },
})

import { OllamaEmbeddings } from '@langchain/ollama'
import { QdrantVectorStore } from '@langchain/qdrant'

const embeddings = new OllamaEmbeddings({
  // 用于生成文本向量的本地模型
  model: 'bge-m3',
  // Ollama 服务地址
  baseUrl: 'http://localhost:11434',
})

export const vectorStore = new QdrantVectorStore(
  // 用于生成文档向量和查询向量的 Embedding 模型
  embeddings,
  // Qdrant 连接和 Collection 配置
  {
    // Qdrant REST API 地址
    url: process.env.QDRANT_URL ?? 'http://localhost:6333',
    // 存放文档块的 Collection 名称
    collectionName: 'rag_documents',
  }
)

import { readFile } from 'node:fs/promises'
import { Document } from '@langchain/core/documents'
import { PDFParse } from 'pdf-parse'

/**
 * 读取本地 PDF 并转换为 LangChain 文档。
 * @param filePath PDF 文件路径。
 */
async function loadPdf(filePath: string) {
  const parser = new PDFParse({
    // 从本地 PDF 读取的二进制数据
    data: await readFile(filePath),
  })

  try {
    // 不传参数时提取全部页面的文本
    const result = await parser.getText()
    return result.pages
      .filter((page) => page.text.trim())
      .map(
        (page) =>
          new Document({
            // 参与切块和检索的当前页正文
            pageContent: page.text,
            // 随文档块保留的文件路径和页码
            metadata: { source: filePath, pageNumber: page.num },
          })
      )
  } finally {
    // 释放解析器占用的资源
    await parser.destroy()
  }
}

import { RecursiveCharacterTextSplitter } from '@langchain/textsplitters'

const splitter = new RecursiveCharacterTextSplitter({
  // 每个文档块的最大字符数
  chunkSize: 500,
  // 相邻文档块重叠的字符数
  chunkOverlap: 50,
})

import { vectorStore } from './vector-store'

/**
 * 为指定 PDF 建立索引。
 * @param filePath 要建立索引的 PDF 文件路径。
 */
export async function indexDocument(filePath: string) {
  // loadPdf 接收文件路径，返回要切分的 PDF 文档
  const documents = await loadPdf(filePath)

  // splitDocuments 接收文档列表，返回切分后的文档块
  const chunks = await splitter.splitDocuments(documents)

  // addDocuments 接收文档块，并生成向量后写入 Qdrant
  await vectorStore.addDocuments(chunks)
}

import { indexDocument } from './indexing'

// 要建立索引的 PDF 文件路径
await indexDocument('docs/handbook.pdf')

import { vectorStore } from './vector-store'

export const retriever = vectorStore.asRetriever({
  // 每次检索返回的文档块数量
  k: 4,
})

import type { Document } from '@langchain/core/documents'

/**
 * 将检索到的文档块整理为带来源编号的上下文。
 * @param documents 检索器返回的文档块。
 */
export function formatDocuments(documents: Document[]) {
  return documents
    .map((document, index) => {
      const source = String(document.metadata.source ?? '未知来源')
      const pageNumber = document.metadata.pageNumber
      const citation = pageNumber ? `${source}，第 ${pageNumber} 页` : source
      return `[${index + 1}] 来源：${citation}\n${document.pageContent}`
    })
    .join('\n\n')
}

import { ChatPromptTemplate } from '@langchain/core/prompts'

// 参数为按顺序发送给模型的消息模板
const prompt = ChatPromptTemplate.fromMessages([
  // system 消息用于约束回答范围和引用格式
  [
    'system',
    `你是一个问答助手。请严格根据提供的资料回答问题。
如果资料中没有答案，直接回答“我不知道”，不要编造。
回答时使用 [1][2] 这样的编号标注引用来源。`,
  ],
  // human 消息通过占位符接收检索上下文和用户问题
  ['human', '资料：\n{context}\n\n问题：{question}'],
])

import { StringOutputParser } from '@langchain/core/output_parsers'
import { RunnablePassthrough, RunnableSequence } from '@langchain/core/runnables'
import { model } from './model'

export const ragChain = RunnableSequence.from([
  // 第一项接收用户问题，并生成提示词需要的两个字段
  {
    // 检索相关文档，再将 Document[] 整理为上下文字符串
    context: retriever.pipe(formatDocuments),
    // 原样保留用户问题
    question: new RunnablePassthrough(),
  },
  // 使用 context 和 question 生成消息列表
  prompt,
  // 使用消息列表调用聊天模型
  model,
  // 将模型返回的消息转换为字符串
  new StringOutputParser(),
])

import { ragChain } from './chain'

// 参数为 RAG 链接收的用户问题
const answer = await ragChain.invoke('退款被驳回后怎么处理？')
console.log(answer)

// 参数与 invoke 相同，均为用户问题字符串
const stream = await ragChain.stream('退款被驳回后怎么处理？')

for await (const chunk of stream) {
  process.stdout.write(chunk)
}

import { tool } from 'langchain'
import * as z from 'zod'
import { formatDocuments, retriever } from './chain'

const searchDocuments = tool(
  // 接收通过 schema 校验的 query 并执行检索
  async ({ query }) => {
    const documents = await retriever.invoke(query)
    return formatDocuments(documents)
  },
  // 提供给模型的工具定义
  {
    // 工具名称
    name: 'search_documents',
    // 帮助模型判断何时调用该工具
    description: '从知识库检索业务规则、流程和错误码等资料。',
    // 约束工具参数的名称和类型
    schema: z.object({
      // 用于召回文档的问题或关键词
      query: z.string().describe('用于检索的问题或关键词'),
    }),
  }
)

import { createAgent } from 'langchain'
import { model } from './model'

const agent = createAgent({
  // 负责选择工具和生成答案的聊天模型
  model,
  // Agent 可以调用的工具列表
  tools: [searchDocuments],
  // 约束 Agent 何时检索以及如何回答
  systemPrompt: `你是问答助手。涉及业务规则、流程或错误码时，先调用 search_documents。
严格根据检索结果回答；资料中没有答案时，直接回答“我不知道”，不要编造。`,
})

const result = await agent.invoke({
  // 本次调用的对话消息
  messages: [
    {
      // 消息发送者
      role: 'user',
      // 用户输入的内容
      content: '退款被驳回后怎么处理？',
    },
  ],
})

// messages 的最后一项是 Agent 的最终回复
console.log(result.messages.at(-1)?.text)

const stream = await agent.stream(
  {
    // 本次调用的对话消息
    messages: [
      {
        // 消息发送者
        role: 'user',
        // 用户输入的内容
        content: '退款被驳回后怎么处理？',
      },
    ],
  },
  {
    // 每一步都返回当前完整的 Agent 状态
    streamMode: 'values',
  }
)

for await (const state of stream) {
  // 输出当前步骤新增的最后一条消息
  console.log(state.messages.at(-1))
}