CoreNLP包含一个简单的Web API服务器,用于满足人类语言理解需求(从3.6.0版开始)。本页介绍了如何进行设置。CoreNLP服务器提供了一种方便的图形方式来与您安装CoreNLP进行交互,以及一个使用任何编程语言调用CoreNLP的API。如果您正在编写CoreNLP的新包装以便以其他语言使用它,建议您使用CoreNLP服务器执行此操作。
Stanford CoreNLP附带内置服务器,只需要CoreNLP依赖项。要运行此服务器,只需运行:
<span style="color:#333333"><span style="color:#77777a"><code><span style="color:#999988"><em># Run the server using all jars in the current directory (e.g., the CoreNLP home directory)</em></span>
java <span style="color:#000080">-mx4g</span> <span style="color:#000080">-cp</span> <span style="color:#dd1144">"*"</span> edu.stanford.nlp.pipeline.StanfordCoreNLPServer <span style="color:#000080">-port</span> 9000 <span style="color:#000080">-timeout</span> 15000
</code></span></span>
请注意,超时以毫秒为单位。
如果要处理非英语语言,请使用此命令以及相应的语言属性:
<span style="color:#333333"><span style="color:#77777a"><code><span style="color:#999988"><em># Run a server using Chinese properties</em></span>
java <span style="color:#000080">-Xmx4g</span> <span style="color:#000080">-cp</span> <span style="color:#dd1144">"*"</span> edu.stanford.nlp.pipeline.StanfordCoreNLPServer <span style="color:#000080">-serverProperties</span> StanfordCoreNLP-chinese.properties <span style="color:#000080">-port</span> 9000 <span style="color:#000080">-timeout</span> 15000
</code></span></span>
每种语言都有一个模型jar,它也必须在CLASSPATH上。可在此处找到每种语言的最新模型罐。
如果未port
提供任何值,则默认使用端口9000。然后,您可以访问来测试您的服务器
<span style="color:#333333"><span style="color:#77777a"><code>http://localhost:9000/
</code></span></span>
您应该会看到一个类似于corenlp.run的网站,其中包含一个文本输入框和一个可以运行的注释器列表。在此界面中,您可以通过在此列表中添加/删除注释器来测试每个注释器。(注意:第一次使用 模型加载时响应速度很慢 - 可能需要30秒左右,但之后服务器应该运行得非常快。)您可以通过向POST
服务器发送请求来测试API。适当的属性。一个简单的方法是使用wget。下面将用部分语音标签注释“ 快速的棕色狐狸跳过懒狗 ” 的句子:
<span style="color:#333333"><span style="color:#77777a"><code>wget <span style="color:#000080">--post-data</span> <span style="color:#dd1144">'The quick brown fox jumped over the lazy dog.'</span> <span style="color:#dd1144">'localhost:9000/?properties={"annotators":"tokenize,ssplit,pos","outputFormat":"json"}'</span> <span style="color:#000080">-O</span> -
</code></span></span>
或者如果你只有或更喜欢卷曲:
<span style="color:#333333"><span style="color:#77777a"><code>curl <span style="color:#000080">--data</span> <span style="color:#dd1144">'The quick brown fox jumped over the lazy dog.'</span> <span style="color:#dd1144">'http://localhost:9000/?properties={%22annotators%22%3A%22tokenize%2Cssplit%2Cpos%22%2C%22outputFormat%22%3A%22json%22}'</span> <span style="color:#000080">-o</span> -
</code></span></span>
本文档的其余部分:更详细地描述API,将API作为API客户端描述为StanfordCoreNLP
注释管道的替代品,并讨论管理服务器。
服务器的最大优势是能够对其进行API调用。
注:请不要不作针对API调用corenlp.run。它没有设置为处理大量请求。有关设置自己的服务器的说明,请参阅“ 专用服务器”部分。
服务器提供了三个端点,我们将在下面详细介绍。它们中的每一个都将一系列url参数作为输入,以及POST
由序列化文档或要注释的原始文本组成的数据。端点是:
/
提供使用CoreNLP注释文档的界面。/tokensregex
提供了一个用于查询TokensRegex模式文本的接口,一旦使用CoreNLP进行注释(使用上面的enpoint)。/semgrex
与/tokensregex
上面类似,此端点将文本与semgrex模式匹配。/
此端点将密钥下的JSON格式的属性字符串作为输入properties=<properties>
,并作为POST
要注释的数据文本。这些属性应镜像传递到CoreNLP命令行的属性文件,但格式化为JSON对象除外。该 POST
数据应百分比编码(也称为URL编码)。特别是,你应该认为%符号为 %25
。(通过Web服务调用CoreNLP的接口应该为其用户进行转义。)
例如,以下命令将标记输入文本,运行词性标注,并将结果作为JSON输出到标准输出:
<span style="color:#333333"><span style="color:#77777a"><code>wget <span style="color:#000080">--post-data</span> <span style="color:#dd1144">'the quick brown fox jumped over the lazy dog'</span> <span style="color:#dd1144">'localhost:9000/?properties={"annotators": "tokenize,ssplit,pos", "outputFormat": "json"}'</span> <span style="color:#000080">-O</span> -
</code></span></span>
要设置的公共属性是API的输出格式。服务器支持CoreNLP提供的所有输出格式。下面列出了它们及其相关属性:
{"outputFormat": "json"}
。{"outputFormat": "xml"}
。{"outputFormat": "text"}
。<span style="color:#333333"><span style="color:#77777a"><code>{"outputFormat": "serialized",
"serializer": "edu.stanford.nlp.pipeline.ProtobufAnnotationSerializer"}
</code></span></span>
目前支持的序列化程序是:
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={...}
:
<span style="color:#333333"><span style="color:#77777a"><code>{<span style="color:#dd1144">"inputFormat"</span>: <span style="color:#dd1144">"serialized"</span>,
<span style="color:#dd1144">"inputSerializer"</span>: <span style="color:#dd1144">"edu.stanford.nlp.pipeline.ProtobufAnnotationSerializer"</span>}
</code></span></span>
对服务器的完整调用,将路径中的protobuf序列化文档作为输入/path/to/file.proto
,并作为响应返回文档的protobuf,注释为部分语音和命名实体标记(对于文件/path/to/annotated_file.proto
可以是:
<span style="color:#333333"><span style="color:#77777a"><code>wget <span style="color:#000080">--post-file</span> /path/to/file.proto <span style="color:#dd1144">'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"}'</span> <span style="color:#000080">-O</span> /path/to/annotated_file.proto
</code></span></span>
/tokensregex
与CoreNLP目标类似,/tokensregex
将数据块(例如,文本)作为POST
数据和一系列url参数。目前,仅POST
支持纯文本数据。两个相关的url参数是:
pattern
:要标注的TokensRegex模式。filter
:如果为true,则整个句子必须与模式匹配,而不是API查找匹配部分。响应始终采用JSON格式,格式如下:
<span style="color:#333333"><span style="color:#77777a"><code>{<span style="color:#dd1144">"sentences"</span>: {
<span style="color:#dd1144">"0"</span>: {
<span style="color:#dd1144">"text"</span>: <span style="color:#dd1144">"the matched text"</span>,
<span style="color:#dd1144">"begin"</span>: <span style="color:#009999">2</span>,
<span style="color:#dd1144">"end"</span>: <span style="color:#009999">5</span>,
<span style="color:#dd1144">"$captureGroupKey"</span>: {
<span style="color:#dd1144">"text"</span>: <span style="color:#dd1144">"the matched text"</span>,
<span style="color:#dd1144">"begin"</span>: <span style="color:#009999">2</span>,
<span style="color:#dd1144">"end"</span>: <span style="color:#009999">5</span>,
}
}
}
}
</code></span></span>
/semgrex
与CoreNLP目标类似,与TokensRegex几乎相同,/semgrex
将数据块(例如,文本)作为POST
数据和一系列url参数。目前,仅POST
支持纯文本数据。两个相关的url参数是:
pattern
:Semgrex模式注释。filter
:如果为true,则整个句子必须与模式匹配,而不是API查找匹配部分。响应始终为JSON,格式与tokensregex输出相同,但所有跨度都是单个单词(仅返回匹配的根):
<span style="color:#333333"><span style="color:#77777a"><code>{<span style="color:#dd1144">"sentences"</span>: {
<span style="color:#dd1144">"0"</span>: {
<span style="color:#dd1144">"text"</span>: <span style="color:#dd1144">"text"</span>,
<span style="color:#dd1144">"begin"</span>: <span style="color:#009999">4</span>,
<span style="color:#dd1144">"end"</span>: <span style="color:#009999">5</span>,
<span style="color:#dd1144">"$captureGroupKey"</span>: {
<span style="color:#dd1144">"text"</span>: <span style="color:#dd1144">"text"</span>,
<span style="color:#dd1144">"begin"</span>: <span style="color:#009999">4</span>,
<span style="color:#dd1144">"end"</span>: <span style="color:#009999">5</span>,
}
}
}
}
</code></span></span>
CoreNLP包括服务器的Java客户端StanfordCoreNLPClient
- 它StanfordCoreNLP.java
尽可能地反映注释管道()的接口。使用此类而不是本地管道的主要激励用例是:
构造函数StanfordCoreNLPClient
采用以下3个必需参数,以及第四个可选参数:
Properties props
:精确镜像本地管道,这些是使用管道注释文本时要使用的属性。最低限度,它指定要运行的注释器。String host
:服务器的主机名。int port
:运行服务器的端口。int threads
:可选地,用于命中服务器的线程数。例如,如果服务器在8核计算机上运行,则可以将其指定为8,并且客户端将允许您向服务器发出8个同时请求。请注意,没有什么可以确保您在服务器上保留这些线程:两个客户端都可以使用8个线程命中服务器,服务器只会响应一半的速度。客户端的一个示例程序用法,在localhost:9000上命中服务器,最多2个线程,如下所示。请注意,这恰好反映了传统管道的使用情况。
<span style="color:#333333"><span style="color:#77777a"><code><span style="color:#999988"><em>// creates a StanfordCoreNLP object with POS tagging, lemmatization, NER, parsing, and coreference resolution</em></span>
Properties props <strong>=</strong> <strong>new</strong> Properties<strong>();</strong>
props<strong>.</strong><span style="color:#008080">setProperty</span><strong>(</strong><span style="color:#dd1144">"annotators"</span><strong>,</strong> <span style="color:#dd1144">"tokenize, ssplit, pos, lemma, ner, parse, dcoref"</span><strong>);</strong>
StanfordCoreNLPClient pipeline <strong>=</strong> <strong>new</strong> StanfordCoreNLPClient<strong>(</strong>props<strong>,</strong> <span style="color:#dd1144">"http://localhost"</span><strong>,</strong> <span style="color:#009999">9000</span><strong>,</strong> <span style="color:#009999">2</span><strong>);</strong>
<span style="color:#999988"><em>// read some text in the text variable</em></span>
String text <strong>=</strong> <strong>...</strong> <span style="color:#999988"><em>// Add your text here!</em></span>
<span style="color:#999988"><em>// create an empty Annotation just with the given text</em></span>
Annotation document <strong>=</strong> <strong>new</strong> Annotation<strong>(</strong>text<strong>);</strong>
<span style="color:#999988"><em>// run all Annotators on this text</em></span>
pipeline<strong>.</strong><span style="color:#008080">annotate</span><strong>(</strong>document<strong>);</strong>
</code></span></span>
您还可以从命令行运行客户端,并获取类似于本地CoreNLP程序的命令行用法的界面。以下内容将使用input.txt
词性,词条,命名实体,选区解析和共指来注释文件:
<span style="color:#333333"><span style="color:#77777a"><code>java <span style="color:#000080">-cp</span> <span style="color:#dd1144">"*"</span> <span style="color:#000080">-Xmx1g</span> edu.stanford.nlp.pipeline.StanfordCoreNLPClient <span style="color:#000080">-annotators</span> tokenize,ssplit,pos,lemma,ner,parse,dcoref <span style="color:#000080">-file</span> input.txt
</code></span></span>
注:同样,请不要不作针对API调用
http://corenlp.run
。它没有设置为处理大量请求。有关设置自己的服务器的说明,请参阅“ 专用服务器”部分。
一旦设置了自己的服务器,就可以使用如下命令对它们进行操作:
<span style="color:#333333"><span style="color:#77777a"><code>java edu.stanford.nlp.pipeline.StanfordCoreNLPClient <span style="color:#000080">-cp</span> <span style="color:#dd1144">"*"</span> <span style="color:#000080">-annotators</span> tokenize,ssplit,pos,lemma,ner,parse,dcoref <span style="color:#000080">-file</span> input.txt <span style="color:#000080">-backends</span> http://localhost:9000
</code></span></span>
您可以在逗号分隔列表中指定一个或多个后端服务器作为-backends
选项的参数。每个都指定为host:port
。
如果服务器在其类路径中具有可用的外语模型,则可以要求它使用其他语言的文本。如果你有法语属性文件和french.txt
当前目录中调用的文件,那么你应该能够成功地给出如下命令:
<span style="color:#333333"><span style="color:#77777a"><code>java <span style="color:#000080">-cp</span> <span style="color:#dd1144">"*"</span> edu.stanford.nlp.pipeline.StanfordCoreNLPClient <span style="color:#000080">-props</span> StanfordCoreNLP-french.properties <span style="color:#000080">-annotators</span> tokenize,ssplit,pos,depparse ile french.txt <span style="color:#000080">-outputFormat</span> conllu <span style="color:#000080">-backends</span> localhost:9000
</code></span></span>
现在有几种编程语言的模块,包括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上。关闭服务器的示例命令是:
<span style="color:#333333"><span style="color:#77777a"><code>wget <span style="color:#dd1144">"localhost:9000/shutdown?key=</span><span style="color:#dd1144">`</span><span style="color:#0086b3">cat</span> /tmp/corenlp.shutdown<span style="color:#dd1144">`</span><span style="color:#dd1144">"</span> <span style="color:#000080">-O</span> -
</code></span></span>
如果使用-server_id SERVER_NAME
它启动服务器,则会将关闭密钥存储在名为的文件中corenlp.shutdown.SERVER_NAME
。
您可以通过要求用户名和密码来限制对服务器的访问。
<span style="color:#333333"><span style="color:#77777a"><code>java <span style="color:#000080">-Xmx4g</span> edu.stanford.nlp.pipeline.StanfordCoreNLPServer <span style="color:#000080">-port</span> 9000 <span style="color:#000080">-timeout</span> 15000 <span style="color:#000080">-username</span> myUsername <span style="color:#000080">-password</span> myPassword
</code></span></span>
以下是向服务器发出请求,提供用户名和密码的示例。
<span style="color:#333333"><span style="color:#77777a"><code>wget <span style="color:#000080">--user</span> myUsername <span style="color:#000080">--password</span> myPassword <span style="color:#000080">--post-data</span> <span style="color:#dd1144">'The quick brown fox jumped over the lazy dog.'</span> <span style="color:#dd1144">'localhost:9000/?properties={"outputFormat":"json"}'</span> <span style="color:#000080">-O</span> -
</code></span></span>
服务器可以采用许多命令行标志,如下所示:
旗 | 参数类型 | 默认 | 描述 |
---|---|---|---|
-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权限:
/opt/corenlp
。代码将在一个名为的jar中stanford-corenlp-<version>.jar
。模型将在一个名为的罐子里stanford-corenlp-<version>-models.jar
; 此处还可以添加其他语言,无壳或移位减少模型。CoreNLP版本中包含的最小库依赖项是:
joda-time.jar
jollyday-<version>.jar
protobuf.jar
xom-<version>.jar
安装authbind。在Ubuntu上,这很简单sudo apt-get install authbind
。
创建具有nlp
读取目录权限的用户/opt/corenlp
。允许用户绑定到端口80:
<span style="color:#333333"><span style="color:#77777a"><code> <span style="color:#0086b3">sudo </span>mkdir <span style="color:#000080">-p</span> /etc/authbind/byport/
<span style="color:#0086b3">sudo </span>touch /etc/authbind/byport/80
<span style="color:#0086b3">sudo </span>chown nlp:nlp /etc/authbind/byport/80
<span style="color:#0086b3">sudo </span>chmod 600 /etc/authbind/byport/80
</code></span></span>
在路径将复制源罐子启动脚本edu/stanford/nlp/pipeline/demo/corenlp
来/etc/init.d/corenlp
。一个简单的方法是:
<span style="color:#333333"><span style="color:#77777a"><code> <span style="color:#0086b3">sudo </span>wget https://raw.githubusercontent.com/stanfordnlp/CoreNLP/master/src/edu/stanford/nlp/pipeline/demo/corenlp <span style="color:#000080">-O</span> /etc/init.d/corenlp
</code></span></span>
为启动脚本提供可执行权限: sudo chmod a+x /etc/init.d/corenlp
将脚本链接到/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。我们没有尝试过,但相信相应的事情是:
<span style="color:#333333"><span style="color:#77777a"><code> <span style="color:#0086b3">sudo </span>wget https://raw.githubusercontent.com/stanfordnlp/CoreNLP/master/src/edu/stanford/nlp/pipeline/demo/corenlp <span style="color:#000080">-O</span> /etc/init/corenlp
initctl reload-configuration
</code></span></span>
CoreNLP服务器现在将在启动时启动,在用户下的端口80上运行nlp
。要手动启动/停止/重新启动服务器,您可以使用:
<span style="color:#333333"><span style="color:#77777a"><code><span style="color:#0086b3">sudo </span>service corenlp <strong>[</strong>start|stop|restart]
</code></span></span>
本节介绍了服务器的一些细微之处,以及它们背后的动机。
官方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+Enter
Web演示中的任何输入字段(例如,主文本输入)等同于单击Submit
(或Match
)按钮。此外,如果输入为空,它将使用默认输入填充自身。有用的 - 如果 - 以一个纯粹的假设示例 - 您正在开发Web服务器,并且不希望每次重新加载网站时重新键入相同的句子。在为shell脚本启动服务器实例时,请确保在与服务器交互之前等待服务器可用。netcat
在linux上使用该工具的一个例子:
<span style="color:#333333"><span style="color:#77777a"><code><span style="color:#999988"><em>#!/bin/bash</em></span>
java <span style="color:#000080">-mx4g</span> edu.stanford.nlp.pipeline.StanfordCoreNLPServer &
<span style="color:#999988"><em># Wait until server starts</em></span>
<strong>while</strong> <strong>!</strong> nc <span style="color:#000080">-z</span> localhost 9000; <strong>do
</strong>sleep 0.1 <span style="color:#999988"><em># wait for 1/10 of the second before check again</em></span>
<strong>done</strong>
<span style="color:#999988"><em># Rest of script</em></span>
<span style="color:#999988"><em># ...</em></span>
</code></span></span>
如果您在生产环境中,还可以等待liveness(/live
)和readyiness(/ready
)端点检查服务器是否在线(活动)并准备好分别接受连接(准备就绪)。这些镜像反映了Kubernetes活性和就绪探测的语义,并且可以兼作服务器的运行状况检查。