Stanford CoreNLP服务器

CoreNLP服务器

• 入门
• API文档
  • 使用CoreNLP进行批注： /
  • 查询TokensRegex： /tokensregex
  • 查询Semgrex： /semgrex
• Java客户端
• 通过其他编程语言使用
• 服务器管理
  • 启动服务器
  • 搬运工人
  • 停止服务器
  • 添加用户名/密码验证
  • 命令行标志
  • 专用服务器
• 怪癖和细微之处
  • 字符编码
  • 默认属性
  • 未记载的功能
  • 服务器准备就绪

CoreNLP包含一个简单的Web API服务器，用于满足人类语言理解需求（从3.6.0版开始）。本页介绍了如何进行设置。CoreNLP服务器提供了一种方便的图形方式来与您安装CoreNLP进行交互，以及一个使用任何编程语言调用CoreNLP的API。如果您正在编写CoreNLP的新包装以便以其他语言使用它，建议您使用CoreNLP服务器执行此操作。

入门

Stanford CoreNLP附带内置服务器，只需要CoreNLP依赖项。要运行此服务器，只需运行：

# Run the server using all jars in the current directory (e.g., the CoreNLP home directory)
java -mx4g -cp "*" edu.stanford.nlp.pipeline.StanfordCoreNLPServer -port 9000 -timeout 15000

请注意，超时以毫秒为单位。

如果要处理非英语语言，请使用此命令以及相应的语言属性：

# Run a server using Chinese properties
java -Xmx4g -cp "*" edu.stanford.nlp.pipeline.StanfordCoreNLPServer -serverProperties StanfordCoreNLP-chinese.properties -port 9000 -timeout 15000

每种语言都有一个模型jar，它也必须在CLASSPATH上。可在此处找到每种语言的最新模型罐。

如果未port提供任何值，则默认使用端口9000。然后，您可以访问来测试您的服务器

http://localhost:9000/

您应该会看到一个类似于corenlp.run的网站，其中包含一个文本输入框和一个可以运行的注释器列表。在此界面中，您可以通过在此列表中添加/删除注释器来测试每个注释器。（注意：第一次使用 模型加载时响应速度很慢 - 可能需要30秒左右，但之后服务器应该运行得非常快。）您可以通过向POST服务器发送请求来测试API。适当的属性。一个简单的方法是使用wget。下面将用部分语音标签注释“ 快速的棕色狐狸跳过懒狗 ” 的句子：

wget --post-data 'The quick brown fox jumped over the lazy dog.' 'localhost:9000/?properties={"annotators":"tokenize,ssplit,pos","outputFormat":"json"}' -O -

或者如果你只有或更喜欢卷曲：

curl --data 'The quick brown fox jumped over the lazy dog.' 'http://localhost:9000/?properties={%22annotators%22%3A%22tokenize%2Cssplit%2Cpos%22%2C%22outputFormat%22%3A%22json%22}' -o -

本文档的其余部分：更详细地描述API，将API作为API客户端描述为StanfordCoreNLP注释管道的替代品，并讨论管理服务器。

API文档

服务器的最大优势是能够对其进行API调用。

注：请不要不作针对API调用corenlp.run。它没有设置为处理大量请求。有关设置自己的服务器的说明，请参阅“ 专用服务器”部分。

服务器提供了三个端点，我们将在下面详细介绍。它们中的每一个都将一系列url参数作为输入，以及POST由序列化文档或要注释的原始文本组成的数据。端点是：

• / 提供使用CoreNLP注释文档的界面。
• /tokensregex 提供了一个用于查询TokensRegex模式文本的接口，一旦使用CoreNLP进行注释（使用上面的enpoint）。
• /semgrex与/tokensregex上面类似，此端点将文本与semgrex模式匹配。

使用CoreNLP进行批注： /

此端点将密钥下的JSON格式的属性字符串作为输入properties=，并作为POST要注释的数据文本。这些属性应镜像传递到CoreNLP命令行的属性文件，但格式化为JSON对象除外。该 POST数据应百分比编码（也称为URL编码）。特别是，你应该认为％符号为 %25。（通过Web服务调用CoreNLP的接口应该为其用户进行转义。）

例如，以下命令将标记输入文本，运行词性标注，并将结果作为JSON输出到标准输出：

wget --post-data 'the quick brown fox jumped over the lazy dog' 'localhost:9000/?properties={"annotators": "tokenize,ssplit,pos", "outputFormat": "json"}' -O -

要设置的公共属性是API的输出格式。服务器支持CoreNLP提供的所有输出格式。下面列出了它们及其相关属性：

• JSON：以JSON格式打印注释。这对应于属性：{"outputFormat": "json"}。
• XML：以XML格式打印注释。这对应于属性：{"outputFormat": "xml"}。
• 文本：以人类可读的文本格式打印注释。这是CoreNLP命令行界面的默认格式。这对应于属性：{"outputFormat": "text"}。
• 序列化：以无损序列化格式打印注释。当从支持其中一种序列化格式的语言以编程方式调用API时，这是推荐的选项。除了设置输出格式标志外，还必须提供有效的序列化程序类。例如，对于协议缓冲区，这将是：

  {"outputFormat": "serialized", 
   "serializer": "edu.stanford.nlp.pipeline.ProtobufAnnotationSerializer"}
  

  目前支持的序列化程序是：

  • edu.stanford.nlp.pipeline.ProtobufAnnotationSerializer将输出写入协议缓冲区，如定义文件中所定义edu.stanford.nlp.pipeline.CoreNLP.proto。
  • edu.stanford.nlp.pipeline.GenericAnnotationSerializer将输出写入Java序列化对象。这仅适用于在Java程序之间传输数据。这也会产生相对较大的序列化对象。
  • edu.stanford.nlp.pipeline.CustomAnnotationSerializer将输出写入（有损！）文本表示，该表示远小于GenericAnnotationSerializer但不包括所有相关信息。

服务器还接受各种格式的输入。默认情况下，它将输入作为原始文本作为POST数据发送到服务器。但是，它也可以配置为POST使用其中一个CoreNLP序列化程序读取数据。这可以通过设置属性inputFormat和来设置inputSerializer。例如，要将数据作为协议缓冲区读取（例如，如果已经部分注释，则非常有用），只需在url参数中包含以下内容properties={...}：

{"inputFormat": "serialized",
 "inputSerializer": "edu.stanford.nlp.pipeline.ProtobufAnnotationSerializer"}

对服务器的完整调用，将路径中的protobuf序列化文档作为输入/path/to/file.proto，并作为响应返回文档的protobuf，注释为部分语音和命名实体标记（对于文件/path/to/annotated_file.proto可以是：

wget --post-file /path/to/file.proto 'localhost:9000/?properties={"inputFormat": "serialized", "inputSerializer", "edu.stanford.nlp.pipeline.ProtobufAnnotationSerializer", "annotators": "tokenize,ssplit,pos,lemma,ner", "outputFormat": "serialized", "serializer", "edu.stanford.nlp.pipeline.ProtobufAnnotationSerializer"}' -O /path/to/annotated_file.proto

查询TokensRegex： /tokensregex

与CoreNLP目标类似，/tokensregex将数据块（例如，文本）作为POST数据和一系列url参数。目前，仅POST支持纯文本数据。两个相关的url参数是：

• pattern：要标注的TokensRegex模式。
• filter：如果为true，则整个句子必须与模式匹配，而不是API查找匹配部分。

响应始终采用JSON格式，格式如下：

{"sentences": {
	"0": {
	  "text": "the matched text",
	  "begin": 2,
	  "end": 5,
	  "$captureGroupKey": {
		  "text": "the matched text",
		  "begin": 2,
		  "end": 5,
            }
        }
    }
}

查询Semgrex： /semgrex

与CoreNLP目标类似，与TokensRegex几乎相同，/semgrex将数据块（例如，文本）作为POST数据和一系列url参数。目前，仅POST支持纯文本数据。两个相关的url参数是：

• pattern：Semgrex模式注释。
• filter：如果为true，则整个句子必须与模式匹配，而不是API查找匹配部分。

响应始终为JSON，格式与tokensregex输出相同，但所有跨度都是单个单词（仅返回匹配的根）：

{"sentences": {
	"0": {
	  "text": "text",
	  "begin": 4,
	  "end": 5,
	  "$captureGroupKey": {
		  "text": "text",
		  "begin": 4,
		  "end": 5,
            }
        }
    }
}

Java客户端

CoreNLP包括服务器的Java客户端StanfordCoreNLPClient- 它StanfordCoreNLP.java尽可能地反映注释管道（）的接口。使用此类而不是本地管道的主要激励用例是：

• 每次程序运行时都不会重新加载模型。这在调试运行CoreNLP注释的代码块时非常有用，因为CoreNLP模型通常需要几分钟才能从磁盘加载。
• 运行服务器的计算机比本地计算机具有更多计算和更多内存。Chrome和CoreNLP再也不会争夺相同的内存。

构造函数StanfordCoreNLPClient采用以下3个必需参数，以及第四个可选参数：

1. Properties props：精确镜像本地管道，这些是使用管道注释文本时要使用的属性。最低限度，它指定要运行的注释器。
2. String host：服务器的主机名。
3. int port：运行服务器的端口。
4. int threads：可选地，用于命中服务器的线程数。例如，如果服务器在8核计算机上运行，​​则可以将其指定为8，并且客户端将允许您向服务器发出8个同时请求。请注意，没有什么可以确保您在服务器上保留这些线程：两个客户端都可以使用8个线程命中服务器，服务器只会响应一半的速度。

客户端的一个示例程序用法，在localhost：9000上命中服务器，最多2个线程，如下所示。请注意，这恰好反映了传统管道的使用情况。

// creates a StanfordCoreNLP object with POS tagging, lemmatization, NER, parsing, and coreference resolution
Properties props = new Properties();
props.setProperty("annotators", "tokenize, ssplit, pos, lemma, ner, parse, dcoref");
StanfordCoreNLPClient pipeline = new StanfordCoreNLPClient(props, "http://localhost", 9000, 2);
// read some text in the text variable
String text = ... // Add your text here!
// create an empty Annotation just with the given text
Annotation document = new Annotation(text);
// run all Annotators on this text
pipeline.annotate(document);

您还可以从命令行运行客户端，并获取类似于本地CoreNLP程序的命令行用法的界面。以下内容将使用input.txt词性，词条，命名实体，选区解析和共指来注释文件：

java -cp "*" -Xmx1g edu.stanford.nlp.pipeline.StanfordCoreNLPClient -annotators tokenize,ssplit,pos,lemma,ner,parse,dcoref -file input.txt

注：同样，请不要不作针对API调用http://corenlp.run。它没有设置为处理大量请求。有关设置自己的服务器的说明，请参阅“ 专用服务器”部分。

一旦设置了自己的服务器，就可以使用如下命令对它们进行操作：

java edu.stanford.nlp.pipeline.StanfordCoreNLPClient -cp "*" -annotators tokenize,ssplit,pos,lemma,ner,parse,dcoref -file input.txt  -backends http://localhost:9000

您可以在逗号分隔列表中指定一个或多个后端服务器作为-backends选项的参数。每个都指定为host:port。

如果服务器在其类路径中具有可用的外语模型，则可以要求它使用其他语言的文本。如果你有法语属性文件和french.txt 当前目录中调用的文件，那么你应该能够成功地给出如下命令：

java -cp "*" edu.stanford.nlp.pipeline.StanfordCoreNLPClient -props StanfordCoreNLP-french.properties -annotators tokenize,ssplit,pos,depparse ile french.txt -outputFormat conllu -backends localhost:9000

通过其他编程语言使用

现在有几种编程语言的模块，包括Python和JavaScript，它们通过与Stanford CoreNLP服务器实例交谈来工作。实际上，现在通常是在其他语言中实现CoreNLP接口的最佳方式。

查看其他编程语言和包页面上的可用内容 。

服务器管理

本节介绍如何管理服务器，包括启动和停止服务器，以及将其设置为启动任务

启动服务器

服务器通过调用它直接启动java。例如，假设您的类路径设置正确，以下将在端口1337的后台启动服务器：

nohup java -mx4g edu.stanford.nlp.pipeline.StanfordCoreNLPServer 1337 &

类路径必须包含所有CoreNLP依赖项。服务器的内存要求与CoreNLP的内存要求相同，但是当您加载更多模型时它会增长（例如，如果加载PCFG和Shift-Reduce选区解析器模型，内存会增加）。安全最低为4gb; 如果您可以节省8gb，建议使用。

搬运工人

Docker repository: https://hub.docker.com/r/frnkenstien/corenlp
docker pull frnkenstien/corenlp

如果在docker下运行服务器，则必须将容器的端口9000发布到主机。给出如下命令：docker run -p 9000:9000 --name coreNLP --rm -i -t frnkenstien/corenlp。如果，当你去localhost:9000/，你看到错误This site can’t be reached. localhost refused to connect，那么这就是你没有做到的！

停止服务器

通过/shutdown使用适当的关键密钥调用端点，可以以编程方式停止服务器。此密钥将保存到服务器启动时corenlp.shutdown指定的目录中的文件中System.getProperty("java.io.tmpdir");。通常情况下/tmp/corenlp.shutdown，虽然它可能会有所不同，尤其是在macOS上。关闭服务器的示例命令是：

wget "localhost:9000/shutdown?key=`cat /tmp/corenlp.shutdown`" -O -

如果使用-server_id SERVER_NAME它启动服务器，则会将关闭密钥存储在名为的文件中corenlp.shutdown.SERVER_NAME。

添加用户名/密码验证

您可以通过要求用户名和密码来限制对服务器的访问。

java -Xmx4g edu.stanford.nlp.pipeline.StanfordCoreNLPServer -port 9000 -timeout 15000 -username myUsername -password myPassword

以下是向服务器发出请求，提供用户名和密码的示例。

wget --user myUsername --password myPassword --post-data 'The quick brown fox jumped over the lazy dog.' 'localhost:9000/?properties={"outputFormat":"json"}' -O -

命令行标志

服务器可以采用许多命令行标志，如下所示：

旗	参数类型	默认	描述
-port	整数	9000	运行服务器的端口。
-status_port	整数	-port	运行活动和准备服务器的端口。默认为在主服务器上运行（即，也在端口9000上）。
-timeout	整数	15000	在取消注释之前等待注释完成的最长时间（以毫秒为单位）。
-strict	布尔	假	如果为true，请严格遵循HTTP标准 - 这意味着除非明确请求，否则不以UTF格式返回！
-quiet	布尔	假	如果为true，请不要将传入的请求记录到stdout（这不会影响CoreNLP的默认日志记录）
-ssl	布尔	假	如果为true，请运行SSL服务器，其中包含* .jks密钥-key。默认情况下，这会加载CoreNLP分发中包含的（非常不安全！）密钥。
-key	串	埃杜/斯坦福/ NLP /管道/ corenlp.jks	用于创建SSL连接的* .jks键的类路径或文件路径
-username	串	“”	除此之外-password，如果设置，则启用具有给定用户名的基本身份验证。
-password	串	“”	除此之外-username，如果设置，则使用给定密码启用基本身份验证。
-annotators	串	所有	如果没有使用注释请求指定注释器，则默认情况下会运行这些注释器。
-preload	串	“”	服务器启动时在缓存中预热的一组注释器。在/ready所有这些注释器都已加载到内存中之前，端点不会响应成功。
-serverProperties	串	“”	如果在实际注释请求中未设置任何属性，则具有服务器应使用的默认属性的文件。例如，用于更改服务器的默认语言。

专用服务器

本节介绍如何在全新Linux安装上设置专用CoreNLP服务器。这些说明在CentOS 6系统上肯定是可以的，这是我们的演示服务器运行的。我们在下面提供了几个不同的注释。与往常一样，请确保您了解下面运行的命令，因为它们主要需要root权限：

1. 将所有CoreNLP jar（代码，模型和库依赖项）放在目录中/opt/corenlp。代码将在一个名为的jar中stanford-corenlp-.jar。模型将在一个名为的罐子里stanford-corenlp--models.jar; 此处还可以添加其他语言，无壳或移位减少模型。CoreNLP版本中包含的最小库依赖项是：
   • joda-time.jar
   • jollyday-.jar
   • protobuf.jar
   • xom-.jar

2. 安装authbind。在Ubuntu上，这很简单sudo apt-get install authbind。

3. 创建具有nlp读取目录权限的用户/opt/corenlp。允许用户绑定到端口80：

    sudo mkdir -p /etc/authbind/byport/
    sudo touch /etc/authbind/byport/80
    sudo chown nlp:nlp /etc/authbind/byport/80
    sudo chmod 600 /etc/authbind/byport/80
   

4. 在路径将复制源罐子启动脚本edu/stanford/nlp/pipeline/demo/corenlp来/etc/init.d/corenlp。一个简单的方法是：

    sudo wget https://raw.githubusercontent.com/stanfordnlp/CoreNLP/master/src/edu/stanford/nlp/pipeline/demo/corenlp -O /etc/init.d/corenlp
   

5. 为启动脚本提供可执行权限： sudo chmod a+x /etc/init.d/corenlp

6. 将脚本链接到/etc/rc.d/： ln -s /etc/init.d/corenlp /etc/rc.d/rc2.d/S75corenlp

   在Ubuntu上，没有介入rc.d目录，所以相当于： ln -s /etc/init.d/corenlp /etc/rc2.d/S75corenlp

上述步骤使用传统的SysVinit脚本。Ubuntu的另一个替代方案是使用Upstart。我们没有尝试过，但相信相应的事情是：

   sudo wget https://raw.githubusercontent.com/stanfordnlp/CoreNLP/master/src/edu/stanford/nlp/pipeline/demo/corenlp -O /etc/init/corenlp
   initctl reload-configuration

CoreNLP服务器现在将在启动时启动，在用户下的端口80上运行nlp。要手动启动/停止/重新启动服务器，您可以使用：

sudo service corenlp [start|stop|restart]

怪癖和细微之处

本节介绍了服务器的一些细微之处，以及它们背后的动机。

字符编码

官方HTTP 1.1规范推荐ISO-8859-1作为请求的编码，除非encoding使用Content-Type标头明确设置了不同的。但是，对于大多数NLP应用程序，这是一个不直观的默认值，因此服务器默认为UTF-8。要启用ISO-8859-1默认值，请-strict在启动时将标志传递给服务器。

默认属性

服务器具有与常规CoreNLP管道不同的默认属性。这些是：

• 默认输出格式json不是text（-outputFormat json）。对于大多数情况，当您对服务器进行API调用时，这更为自然。
• 默认情况下，服务器不会打印输出，而是选择缩小输出。这与设置属性相同-prettyPrint false。
• 默认注释器不包括parse注释器。这主要是为了提高效率。默认情况下启用的注释器为：-annotators tokenize, ssplit, pos, lemma, ner, depparse, coref, natlog, openie。
• 作为没有parse注释器的必然结果，默认的coref提示检测器被更改为使用依赖解析器：-coref.md.type dep。

未记载的功能

好吧，我猜他们现在已经记录在案了：

• 点击Shift+EnterWeb演示中的任何输入字段（例如，主文本输入）等同于单击Submit（或Match）按钮。此外，如果输入为空，它将使用默认输入填充自身。有用的 - 如果 - 以一个纯粹的假设示例 - 您正在开发Web服务器，并且不希望每次重新加载网站时重新键入相同的句子。

服务器准备就绪

在为shell脚本启动服务器实例时，请确保在与服务器交互之前等待服务器可用。netcat在linux上使用该工具的一个例子：

#!/bin/bash
java -mx4g edu.stanford.nlp.pipeline.StanfordCoreNLPServer &
# Wait until server starts
while ! nc -z localhost 9000; do
    sleep 0.1 # wait for 1/10 of the second before check again
done
# Rest of script
# ...

如果您在生产环境中，还可以等待liveness（/live）和readyiness（/ready）端点检查服务器是否在线（活动）并准备好分别接受连接（准备就绪）。这些镜像反映了Kubernetes活性和就绪探测的语义，并且可以兼作服务器的运行状况检查。