Apache UIMA 常用 CLI 命令与工具详解
汇总 Apache UIMA 3.6.1 常用命令行与工具：Maven 生命周期、JCasGen 代码生成、官方 RunAE 运行器、CPE 运行与 jps 堆验证，每条命令均附实测回显与无头环境说明。
Apache UIMA 常用 CLI 命令与工具详解
一、命令行总览
Apache UIMA 3.6.1 服务器端工作流围绕三类命令展开：
| 类别 | 命令/入口 | 用途 |
|---|---|---|
| Maven 生命周期 | mvn clean/compile/package/install | 工程构建 |
| Maven 依赖工具 | mvn dependency:tree / build-classpath / copy-dependencies | 依赖分析与运行 classpath 生成 |
| JCasGen 代码生成 | java org.apache.uima.tools.jcasgen.Jg | 由 TypeSystem 生成 JCas 绑定类 |
| AE 运行器 | java org.apache.uima.tools.RunAE | 官方 CLI：批量文档过分析引擎 |
| CPE 运行 | java + CollectionProcessingEngine API | 集合处理引擎（无官方无头 CLI，走 API） |
| JVM 诊断 | jps / jcmd | 进程与堆参数验证 |
说明：uimaj-tools 构件内的 CVD（CAS Visual Debugger）、Document Analyzer、CPM 均为 Swing 图形工具，实测在无图形环境启动即抛 HeadlessException，本文以命令行与 API 路径为主，GUI 行为如实标注。实测环境：OpenJDK 17 + Maven（Ubuntu 3.6.3 / CentOS 8 官方二进制 3.9.16）+ uimaj 3.6.1。
二、Maven 全生命周期命令
以下命令均在工程根目录 /opt/uima-demo 执行。
2.1 依赖解析与下载
mvn -B dependency:resolve
首次执行把 uimaj-core、uimaj-cpe、uimaj-tools、uimaj-json 及传递依赖下载到 /root/.m2/repository。加 -B 进入批处理模式，去掉下载进度条刷屏。
2.2 编译与打包
mvn -B compile # 编译主代码到 target/classes
mvn -B package # 编译 + 测试 + 打 jar
mvn -B install # 打包并安装到本地仓库，供其他工程依赖
mvn -B clean # 清空 target
实测 mvn -B package 回显（节选）：
[INFO] --- maven-compiler-plugin:3.13.0:compile (default-compile) @ uima-demo ---
[INFO] Compiling 6 source files to /opt/uima-demo/target/classes
[INFO] BUILD SUCCESS
[INFO] Total time: 18.294 s
2.3 依赖树
mvn -B dependency:tree
实测回显（uimaj 3.6.1 全家桶依赖关系一目了然）：
[INFO] com.example:uima-demo:jar:1.0.0
[INFO] +- org.apache.uima:uimaj-core:jar:3.6.1:compile
[INFO] | \- org.slf4j:slf4j-api:jar:1.7.36:compile
[INFO] +- org.apache.uima:uimaj-cpe:jar:3.6.1:compile
[INFO] | +- org.apache.uima:uimaj-adapter-vinci:jar:3.6.1:compile
[INFO] | \- org.apache.uima:jVinci:jar:3.6.1:compile
[INFO] +- org.apache.uima:uimaj-tools:jar:3.6.1:compile
[INFO] +- org.apache.uima:uimaj-json:jar:3.6.1:compile
[INFO] | \- com.fasterxml.jackson.core:jackson-core:jar:2.20.0:compile
[INFO] \- org.slf4j:slf4j-jdk14:jar:1.7.36:runtime
2.4 生成运行 classpath
mvn -B dependency:build-classpath -Dmdep.outputFile=target/cp.txt -q
java -Xms256m -Xmx512m -cp "target/classes:$(cat target/cp.txt)" com.example.uima.RunPipeline
cp.txt 是冒号分隔的依赖 jar 全路径清单，避免了手工拼 classpath。变体命令 dependency:copy-dependencies -DoutputDirectory=lib 可把依赖 jar 拷贝到 lib 目录便于离线分发。
三、JCasGen 代码生成（org.apache.uima.tools.jcasgen.Jg）
3.1 命令格式与实测
M2=~/.m2/repository/org/apache/uima
CP=$M2/uimaj-tools/3.6.1/uimaj-tools-3.6.1.jar:$M2/uimaj-core/3.6.1/uimaj-core-3.6.1.jar:$HOME/.m2/repository/org/slf4j/slf4j-api/1.7.36/slf4j-api-1.7.36.jar
java -cp $CP org.apache.uima.tools.jcasgen.Jg -jcasgeninput descriptors/TypeSystem.xml -jcasgenoutput src/main/java
-jcasgeninput：类型系统描述符（可为文件或目录）。-jcasgenoutput：Java 源码输出目录，包路径按类型名推导。
实测生成 src/main/java/com/example/uima/RoomNumber.java，生成类头部：
/* Apache UIMA v3 - First created by JCasGen Mon Oct 12 14:36:10 GMT 2026 */
package com.example.uima;
import org.apache.uima.jcas.tcas.Annotation;
/** A room number such as 9244-108
* XML source: descriptors/TypeSystem.xml
* @generated */
public class RoomNumber extends Annotation {
UIMA 3 生成的 JCas 类不再有 UIMA 2 时代的 RoomNumber_Type 伴生类。
3.2 实测报错记录
- 缺 slf4j-api：classpath 只有 uimaj-tools 与 uimaj-core 时启动即抛：
Exception in thread "main" java.lang.NoClassDefFoundError: org/slf4j/Logger
解决：把 slf4j-api jar 加入 -cp。仅有 api 没有绑定实现时打印 SLF4J: Defaulting to no-operation (NOP) logger implementation 提示，代码生成功能不受影响。
- 无参数启动进 GUI：
java -cp $CP org.apache.uima.tools.jcasgen.Jg不带参数时尝试打开 Swing 界面，无图形环境抛：
Exception in thread "main" java.awt.HeadlessException:
No X11 DISPLAY variable was set, or no headful library support was found,
but this program performed an operation which requires it.
结论：服务器上必须带 -jcasgeninput/-jcasgenoutput 参数运行。
四、官方 RunAE 工具（org.apache.uima.tools.RunAE）
uimaj-tools 自带命令行分析引擎运行器，输入目录中的每个文件作为一个文档流过 AE，可输出 XMI/XCAS 并打印性能统计。
4.1 用法（无参数运行即打印用法，实测原文）
Usage: java org.apache.uima.tools.RunAE [OPTIONS] <AE descriptor filename> <input dir> [<output dir>]
If <output dir> is not specified, the analysis results will not be output. This can be
useful when only interested in performance statistics.
OPTIONS
-------
-t <TagName> (XML Text Tag) - specifies the name of an XML tag, found within the input
documents, that contains the text to be analyzed. The text will also be detagged. If
this option is not specified, the entire document will be processed.
-q (Quiet) - supresses progress messages that are normally printed as each document is
processed.
-s<x> (Stats level) - determines the verboseness of performance statistics. s0=none,
s1=brief, s2=full. The default is brief.
-x - process input files as XCAS files.
-xmi - process input files as XmiCas files.
-lenient - ignore out-of-typesystem content when deserializing XML files.
-l <ISO language> - specify the ISO Language code to set.
-e <encoding> - specify the character encoding to use.
4.2 实测运行
java -Xms256m -Xmx512m -cp "target/classes:$(cat target/cp.txt)" \
org.apache.uima.tools.RunAE -s2 descriptors/AggregateAE.xml data/in data/out
实测统计输出（节选，-s2 全量统计）：
Event Type: Analysis
Duration: 9ms (14.52%)
Sub-events:
Component Name: RoomNumberAnnotator
Event Type: Analysis
Duration: 3ms (4.84%)
Component Name: RoomNumberCounter
Event Type: Analysis
Duration: 4ms (6.45%)
输出目录实测生成 data/out/room_notes.txt（XCAS XML 格式，文件名沿用输入文件名）：
<?xml version="1.0" encoding="UTF-8"?><Document>
<uima.tcas.DocumentAnnotation sofa="Sofa" begin="0" end="130" language="en">
<org.apache.uima.examples.SourceDocumentInformation sofa="Sofa" begin="0" end="0"
uri="file:/opt/uima-demo/data/in/room_notes.txt" offsetInSource="0" documentSize="...">
RunAE 会在 CAS 中自动补一条 SourceDocumentInformation 注解记录来源 URI。若输入已是 XMI/XCAS，分别用 -xmi / -x 读取。
五、CPE 运行
CPE 无官方无头命令行入口（CPM 工具为 GUI），服务器上用 uimaj-cpe 的 API 直跑，效果等价于"runCPE"。
5.1 编程式构建并运行（实测可运行）
CpeDescription cpeDesc = CpeDescriptorFactory.produceDescriptor(); // org.apache.uima.collection.impl.metadata.cpe 包
cpeDesc.addCollectionReader("descriptors/TextCollectionReader.xml");
CpeCasProcessor annotator = CpeDescriptorFactory.produceCasProcessor("RoomNumberAnnotator");
annotator.setDescriptor("descriptors/RoomNumberAnnotator.xml");
cpeDesc.addCasProcessor(annotator);
cpeDesc.setNumToProcess(-1);
CollectionProcessingEngine engine =
UIMAFramework.produceCollectionProcessingEngine(cpeDesc, Collections.emptyMap());
engine.addStatusCallbackListener(listener); // 实现 StatusCallbackListener 全部方法
engine.process();
实测回显：
[cpe] generated CPE descriptor: /opt/uima-demo/descriptors/RoomNumberCPE.xml
[reader] input directory=/opt/uima-demo/data/in, files found=1
[cpe] initializationComplete - CPE is running
[cpe] document processed, length=130, errors=0
[cpe] collectionProcessComplete - finished
注意两点（均为实测结论）：CpeDescriptorFactory 在 uimaj-cpe 构件的 impl.metadata.cpe 包；回调需实现 initializationComplete/batchProcessComplete/collectionProcessComplete/paused/resumed/aborted/entityProcessComplete 全部方法，缺一个都编译不过。engine.process() 是异步的，JVM 退出时机由回调控制（实测在 collectionProcessComplete 里调用 System.exit(0)）。
5.2 GUI 工具无头实测（如实记录）
$ java -cp $CP org.apache.uima.tools.cvd.CVD
java.awt.HeadlessException:
No X11 DISPLAY variable was set, or no headful library support was found,
but this program performed an operation which requires it.
$ java -cp $CP org.apache.uima.tools.docanalyzer.DocumentAnalyzer
Exception in thread "main" java.awt.HeadlessException: ...
CVD、DocumentAnalyzer、CpmFrame 三个图形工具在无图形服务器均不可用。如必须使用，需要在具备 X11 转发或图形桌面的环境运行；自动化流水线请使用本文三、四、五节的命令行与 API 路径。
六、JVM 诊断命令
6.1 jps：列出 Java 进程并验证启动参数
jps -v
实测回显（Maven 构建期间）：
4887 Launcher -Xms256m -Xmx512m -Dclassworlds.conf=/usr/share/maven/bin/m2.conf ...
实测回显（AE 运行进程）：
7236 RunAE -Xms256m -Xmx512m
6.2 jcmd：运行期 VM 标志
jcmd <pid> VM.flags | tr ' ' '\n' | grep MaxHeapSize
可核对运行进程实际生效的 MaxHeapSize（-Xmx512m 对应 536870912 字节）。程序内亦可直接打印 Runtime.getRuntime().maxMemory()，实测输出：
[heap] effective max heap = 512 MB
七、常见问题
Q1：mvn -B package 报 Source option 5 is no longer supported？
apt/仓库版 Maven 默认绑定的 maven-compiler-plugin 3.1 不识别 maven.compiler.release。解决：pom 中显式声明 maven-compiler-plugin 3.13.0 并配置 <release>17</release>。注意 3.13.0 要求 Maven 3.6.3+，CentOS 8 仓库版 Maven 3.5.4 需改用 Apache 官方二进制包。
Q2：JCasGen 报 UnsupportedClassVersionError ... class file version 61.0？
uimaj-tools 3.6.1 按 Java 17 编译。实测在系统 java 被重置为 1.8 的机器上复现。解决：alternatives --set java java-17-openjdk.x86_64（CentOS）或 update-alternatives --config java（Ubuntu）切回 JDK 17。
Q3：RunAE 处理目录后输出目录没有文件？
实测确认不指定 <output dir> 时只跑统计不落盘。需要分析结果必须提供第三个参数 <output dir>，目录不存在时工具会自动创建。
Q4：java -cp 直跑主类报 ClassNotFoundException？
工程类与依赖 jar 必须同时在 classpath：-cp "target/classes:$(cat target/cp.txt)"。实测漏掉 target/classes 或未生成 cp.txt 都会复现。
Q5：运行时大量 SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder" 输出？
slf4j-api 缺少绑定实现。解决：pom 引入 org.slf4j:slf4j-jdk14:1.7.36（runtime scope），日志汇入 JUL；仅消除告警亦可将日志级别调高屏蔽。
八、参考链接
- Apache UIMA 官方网站：https://uima.apache.org/
- UIMA 工具手册（tools 及 CVD/Document Analyzer 说明）：https://uima.apache.org/doc-uima-overview.html
- uimaj-tools Maven Central 页面：https://central.sonatype.com/artifact/org.apache.uima/uimaj-tools
- GitHub 仓库 apache/uima-uimaj：https://github.com/apache/uima-uimaj
- Apache Maven 命令速查：https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html