最近在开发智能文档搜索的工作中，我需要将各种文件转换为 Markdown 格式，然后通过向量化计算，把它们创建到向量数据库中，以便实现语义搜索文档的功能。并结合 LLMs 和 RAG（Retrieval Augmented Generation）来获取与搜索目标相关的文档内容完成二次创作。由于多模态下需要处理的文档类型太多了，我曾用 python 写了几个工具方法，使用 MarkItDown 来统一处理的。但现实问题是 MarkItDown 目前没有 .NET 版本的实现，而我的应用是 .NET 的程序，如果能有一个办法将 python 脚本无缝嵌入到我的 .NET 应用程序中那就太棒了，这就是我为什么要使用 CSnakes 的原因。

本文将演示我是如何使用 CSnakes 将一个调用了 MarkItDown 的 python 函数脚本嵌入到我的 .NET 应用程序中，让 C# 代码间接完成文档转换的。

Markdown 的好处

主流的大语言模型如 OpenAI 的 GPT-4o，原生就能接受 Markdown，并且常常在未被提示的情况下就在回复中使用 Markdown。这表明它们在大量 Markdown 格式的文本上接受过训练，并且对其“理解”透彻。由于 Markdown 格式的内容对向量检索十分友好, 又很方便插入到结构化的 Prompt 中，因此在 RAG 实践中，Markdown 几乎成了中间数据源默认格式。

MarkItDown 是什么？

MarkItDown 是微软推出的一个轻量级的 Python 实用工具，用于将各种文件（如 PDF、PowerPoint、Word、Excel、Images、HTML、JSON、ZIP 等等）转换为 Markdown 格式，以便与大型语言模型（LLMs）和相关文本分析管道配合使用。它的重点在于将重要的文档结构和内容以 Markdown 格式保留下来，包括标题、列表、表格、链接等。

CSnakes 是什么？

CSnakes 是一个 .NET 源代码生成器和运行时，它将 Python 代码和库以 C-API 层面的方式嵌入到 C#.NET 解决方案中，而无需使用 REST、HTTP 或微服务且具有高性能的运行时效率。在没有 .NET 原生库替代的情况下，CSnakes 可以帮助开发者在 .NET 环境中最快地复用已经稳定运行的 Python 代码，从而保障功能的实现。

关键代码介绍

假定我们有一个 Python 脚本 demo.py，其中有一个 test_convert_pdf 方法，用于将 PDF 文件转换为 Markdown 格式。我们的目标是在 .NET 应用程序中调用这个方法。

1
2
3
4
5
6

from markitdown import MarkItDown

def test_convert_pdf(path: str):
    md = MarkItDown()
    result = md.convert(path)
    return result

创建一个 C# Console 应用程序命名为 CSharpConsoleApp，并添加对 CSnakes.Runtime 的引用。打开项目文件 CSharpConsoleApp.csproj，使用以下内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="CSnakes.Runtime" Version="1.0.27" />
  </ItemGroup>
  
  <ItemGroup>
    <AdditionalFiles Include="demo.py" Link="demo.py" />
    <None Include="requirements.txt" Link="requirements.txt" />
  </ItemGroup>
</Project>

在 .csproj 文件中，除了添加 CSnakes.Runtime 引用外，最重要的是通过 AdditionalFiles 配置节把 Python 脚本文件 demo.py 添加到项目中。在我们运行 dotnet build 时，它会被 CSnakes 发现并编译。

在 Program.cs 文件中，我们可以通过以下代码初始化，并调用 Python 脚本中的函数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

using CSnakes.Runtime;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;


// 定义一个结构体，用于存储文档转换的结果
public record DocumentConvertResult(string Markdown, string Title);

class Program
{
    static void Main(string[] args)
    {
        // 创建主机构建器，用于配置应用程序
        var builder = Host.CreateDefaultBuilder(args)
            .ConfigureServices(services =>
            {
                // 设置Python脚本的目录路径
                var home = Path.Join(Environment.CurrentDirectory, '.');
                // 设置Python虚拟环境的路径
                var venv = Path.Join(home, ".venv");
                // 指定本地Python运行时的路径（MacOS环境下）
                var python_runtime_path = 
                    "/opt/homebrew/Frameworks/Python.framework/Versions/3.12";

                // 配置Python环境
                services
                .WithPython()
                .WithHome(home)
                .WithVirtualEnvironment(venv)
                .FromFolder(python_runtime_path, "3.12")
                .WithPipInstaller();
            });

        // 构建应用程序
        var app = builder.Build();

        // 获取配置好的Python环境服务
        var env = app.Services.GetRequiredService<IPythonEnvironment>();

        // 调用Python脚本中的Demo类和TestConvertPdf方法
        var quickDemo = env.Demo();

        // 将PDF转换为Markdown并获取结果
        var result = quickDemo.TestConvertPdf("assets/test.pdf");

        // 打印转换结果
        Console.WriteLine(result.GetAttr("text_content"));
    }
}

这里要说明一下，我本机是在 MacOS 14.0 上使用 brew install python@3.12安装的 Python，所以我在代码中指定了 Python 的运行时路径如代码所示，大家需要根据自己的环境来配置不同的路径。详细方法可以参考 CSnakes 的文档 Python Locators。

完整的代码示例可以在 https://github.com/BeanHsiang/embedding-markitdown-into-dotnet-demo 中找到。

参考内容