go-xberg-sdk

go-xberg-sdk

基于 Xberg Go binding v1.0.3 的轻量 Go 文档提取 SDK，并提供 CloudWeGo Eino Parser 适配器。 适合把 PDF、Office、图片、邮件、网页和结构化文本转换为 RAG 所需的 Markdown、页面、Chunk 或语义 Element。

包结构

• github.com/sungithubid/go-xberg-sdk/xberg：框架无关的核心 SDK，支持文件、 []byte 和 io.Reader 输入。
• github.com/sungithubid/go-xberg-sdk/components/document/parser/xberg：实现 Eino parser.Parser，支持 Document、Page、Chunk 和 Element 四种输出粒度。

go-xberg-sdk/
├── xberg/                              # 核心 SDK
├── components/document/parser/xberg/   # Eino Parser 适配器
├── examples/                           # core、Eino、OCR 示例
├── scripts/                            # native bundle 依赖收集与路径修正
├── docs/NATIVE_BUNDLE.md               # Release bundle 使用说明
└── .github/workflows/                   # CI 与多平台 Release

交付模型

本项目采用源码与运行时分离的双轨发布方式：

1. Go module 保持轻量：Git tag/module zip 只包含 Go 源码、文档和脚本， 不提交几十到数百 MB 的平台动态库。
2. GitHub Releases 提供 native bundle：每个 release 同时发布 macOS 和 Linux 的三个受支持 OS/架构组合的压缩包及 SHA-256 文件。bundle 包含 libxberg_ffi、递归发现的非系统 sidecar、相对加载路径和许可证。

这意味着 go get 不会自动安装原生库。开发环境可以使用 Xberg 官方 setup； 应用发布时应使用本项目 release 中与目标系统匹配的完整 bundle。

环境要求

• Go 1.26 或更高版本。
• CGO_ENABLED=1 和 C 编译器。
• Go binding 与 native FFI 必须保持同一 Xberg 版本；本项目当前固定为 v1.0.3。
• Linux 构建 release bundle 时需要 patchelf；macOS 使用系统自带的 otool 和 install_name_tool。
• Xberg v1.0.3 没有发布 macOS Intel Go 原生资产，因此当前 release 支持 macOS ARM64、Linux AMD64 和 Linux ARM64。
• Xberg Linux Go 资产自带 ONNX Runtime；macOS 构建机需要安装 libheif。

安装

安装 Go 包

go get github.com/sungithubid/go-xberg-sdk/xberg

# 使用 Eino 时：
go get github.com/sungithubid/go-xberg-sdk/components/document/parser/xberg

开发环境准备 native FFI

在应用模块中运行 Xberg 官方 setup。它会下载并校验与 binding 匹配的原生库， 并为当前应用生成本机链接 shim：

go run github.com/xberg-io/xberg/packages/go/cmd/setup@v1.0.3

克隆本仓库开发时也可以直接运行：

make native
make test

使用 GitHub Release bundle

发布应用时，从同一个 go-xberg-sdk 版本的 GitHub Release 下载目标平台资产：

VERSION=v0.1.0
PLATFORM=linux-x86_64

gh release download "$VERSION" \
  --repo sungithubid/go-xberg-sdk \
  --pattern "go-xberg-sdk-native-${PLATFORM}.tar.gz*"
sha256sum -c "go-xberg-sdk-native-${PLATFORM}.tar.gz.sha256"
tar -xzf "go-xberg-sdk-native-${PLATFORM}.tar.gz"

macOS 可使用 shasum -a 256 -c <checksum-file> 校验。解压后应保持所有 .so/.dylib 位于同一目录；详细部署方式见 bundle 内的 README.md。

构建时把目录传给 CGO：

CGO_ENABLED=1 \
CGO_LDFLAGS="-L/absolute/path/to/go-xberg-sdk-native-linux-x86_64" \
go build ./...

本地运行时还需要设置 LD_LIBRARY_PATH（Linux）或 DYLD_LIBRARY_PATH （macOS）。最终应用也可以把全部库复制到可执行文件同目录，并为可执行文件设置 $ORIGIN/@loader_path RPATH。

核心 SDK 快速开始

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/sungithubid/go-xberg-sdk/xberg"
)

func main() {
    extractor, err := xberg.New(nil)
    if err != nil {
        log.Fatal(err)
    }

    result, err := extractor.ExtractFile(context.Background(), "manual.docx")
    if err != nil {
        log.Fatal(err)
    }

    for _, document := range result.Results {
        fmt.Printf("MIME: %s\n%s\n", document.MimeType, document.Content)
    }
}

Extractor 不持有需要关闭的本地句柄，因此没有 Close 方法，并且可安全并发使用。

除 ExtractFile 外，还支持：

result, err := extractor.ExtractBytes(ctx, data,
    xberg.WithFilename("manual.docx"),
)

result, err = extractor.ExtractReader(ctx, reader,
    xberg.WithFilename("manual.pdf"),
    xberg.WithMIMEType("application/pdf"),
)

ZIP 容器格式（DOCX、XLSX、PPTX）使用内存或 Reader 输入时，建议始终传入 文件名或 MIME hint。

Eino Parser 快速开始

package main

import (
    "context"
    "fmt"
    "os"

    einoparser "github.com/cloudwego/eino/components/document/parser"
    xbergparser "github.com/sungithubid/go-xberg-sdk/components/document/parser/xberg"
)

func main() {
    ctx := context.Background()
    p, err := xbergparser.NewParser(ctx, &xbergparser.Config{
        DocumentMode: xbergparser.DocumentModeChunk,
    })
    if err != nil {
        panic(err)
    }

    file, err := os.Open("manual.pdf")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    docs, err := p.Parse(ctx, file,
        einoparser.WithURI("manual.pdf"),
        einoparser.WithExtraMeta(map[string]any{"knowledge_base": "manuals"}),
    )
    if err != nil {
        panic(err)
    }

    for _, doc := range docs {
        fmt.Printf("%s: %s\n", doc.ID, doc.Content)
    }
}

完整的粒度、OCR、PDF、Chunking 和元数据选项见 Eino Parser 中文文档。高级能力可以用 WithNativeFileConfig 直接透传 Xberg 的单文件配置。

示例与验证

make test
make test-race
make vet
make example-core
make example-eino
make example-ocr OCR_INPUT=/path/to/scan.png

OCR 示例不绑定仓库外的测试文件；调用方必须显式提供图片或扫描 PDF。

构建 native Release

在对应目标平台的原生 runner 上运行：

make release-native VERSION=v0.1.0

该命令会：

1. 从 Xberg 官方 Release 下载并校验 v1.0.3 FFI。
2. 运行 Go 测试。
3. 递归收集非系统动态库依赖和可发现的许可证。
4. 把依赖路径改写为 @loader_path（macOS）或 $ORIGIN（Linux）。
5. 使用打包后的目录重新链接并执行测试。
6. 生成 dist/*.tar.gz 和对应 .sha256。

推送 v* tag 后，release-native workflow 会在三个受支持的 OS/架构 runner 上执行同一流程并上传 GitHub Release。

运行时边界

native bundle 消除了对构建机 Homebrew 路径等非系统动态库的隐式依赖，但不是完全 静态化环境，仍然依赖目标 OS 的动态加载器、基础系统库和兼容的 glibc/macOS 版本。 OCR、布局模型、Embedding、转录等可选能力还可能需要模型文件或网络下载，应在与 生产环境一致的离线镜像中做实际转换测试。

底层 Xberg FFI 是同步调用。context.Context 的 deadline 会转换为 Xberg timeout， 并在调用前后检查取消状态，但不能保证立即中断已经进入 native 的调用。

License

本项目采用 MIT License。Xberg 以及 release bundle 中可发现的 sidecar 许可证分别放在 third_party/ 与 bundle 的 licenses/ 中。正式分发前仍应审核所有 原生编解码依赖的许可证是否符合产品发布方式。